Re: Revamping the developer documentation

[Marta Maria Casetti <mmcasetti gmail com>]

Hi,

First of all: I really like the mockups.

I also think that we should try to include something for first-time
programmers, like a tutorial, somewhere.

I am ready to revise my tutorial for GTK+ for Python and to help with
completing Taryn Fox's GTK+ tutorial for JavaScript (I think that Meg
Ford is working on that, please correct me if I am wrong). I would
need help for the tutorial for C. The first idea for these tutorials
was to have a collection of pages, one for each main widget; each page
consisted of an example, the code for that example, and (for the
Python tutorial) a collection of "useful methods" for that widget or
(for the JavaScript tutorial) a step-by-step guide to the code. For
the Python tutorial I also made a "tutorial" page, with a more
"classic" approach: a walk through these pages and through a couple of
"theory" pages (such as "explain the M/V/C design that is needed for
ComboBox and TreeView"). I think that if we are to separate the "APIs
for more experienced programmers" and the "tutorial for beginners"
(good idea, imho) this "walk through" is the right thing to do for the
latter, and the "one widget, one page" is the right thing to do for
the former.

Please let me know what you think.

Best,
   Marta



On Tue, Feb 26, 2013 at 12:21 AM, Allan Day <allanpday gmail com> wrote:
> Hi all,
>
> As some of you know, I spent some time looking at the developer docs
> during the recent Developer Experience Hackfest. I was also able to
> have a short discussion about it yesterday at the Documentation
> Hackfest in Brno.
>
> Here's a brief summary of the ideas that have come out of these
> discussions so far:
>
>  * It would be great if all the developer documentation could
> consistently reflect a recommended process for developing a GNOME
> application (we sketched this out during the Dev X hackfest: design
> your application, create a UI with Glade, code using the recommended
> editor, test, add documentation, create a package or approach
> distros).
>  * It would also be great if we could work towards having a complete
> set of application development documentation for JavaScript. this
> would align the developer documentation with efforts that are underway
> for tooling and generated API documentation.
>  * In some of the discussions about the target audience for developer
> docs, it was proposed that the docs should be written for people with
> some programming experience, but who might not have been exposed to
> GNOME in the past. It was also suggested that, while we might want to
> have tutorials aimed at developers with different backgrounds (eg.
> Windows/OS X/web development), the core of the docs need to be
> background agnostic. This would imply that we wouldn't have tutorials
> that try to teach programming for the first time on
> developer.gnome.org (which isn't to say that we couldn't have this
> type of material elsewhere).
>  * Another proposal was that developer.gnome.org should be targeted at
> application developers and not core GNOME development (again, this
> isn't to say that we shouldn't have docs for core GNOME development
> somewhere).
>  * Having a more encompassing organisational structure would help us
> to identify what documentation is missing and should also help
> application developers find the help they need. One idea that came out
> of the Documentation Hackfest was that the developer docs could be
> structured around task areas, such as application integration,
> multimedia or creating UI. Each section could then include specific
> development tasks: "Writing a Desktop File", "Playing Audio", "Dialog
> Windows".
>  * We need a new HIG, and it needs to be hosted on developer.gnome.org
> - I'm currently working on this.
>  * It would be better to have a separate website for the user and
> sysadin documentation, so that developer.gnome.org is purely about
> developer docs.
>
> A number of these ideas are reflected in a small set of mockups I've
> done for developer.gnome.org [1, 2, 3]. There has been a bit of work
> done to implement this redesign, and that is something I would like to
> pursue.
>
> All of this is extremely tentative and it would be great to hear
> everyone's thoughts. It would be especially good to hear what the
> existing developer docs writers think.
>
> Allan
> --
> IRC:  aday on irc.gnome.org
> Blog: http://afaikblog.wordpress.com/
>
> [1] https://raw.github.com/gnome-design-team/gnome-web/master/developer.gnome.org/wireframes/png/home.png
> [2] 
> https://raw.github.com/gnome-design-team/gnome-web/master/developer.gnome.org/wireframes/png/tutorials.png
> [3] 
> https://raw.github.com/gnome-design-team/gnome-web/master/developer.gnome.org/wireframes/png/api-reference.png
> _______________________________________________
> gnome-doc-list mailing list
> gnome-doc-list gnome org
> https://mail.gnome.org/mailman/listinfo/gnome-doc-list