Revamping the developer documentation

[Allan Day <allanpday gmail com>]

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