Re: Revamping the developer documentation



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


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]