Re: Revamping the developer documentation

[Allan Day <allanpday gmail com>]

Hi all,

More discussion on #docs today.

Since there's interest in writing documentation for people who are new
to coding, we agreed that it would be good to have a separate area on
developer.gnome.org for beginners. This would allow us to target the
main docs towards experienced programmers, but also have a more
education-orientated area for newbies. I added this to the mockups [1,
2]

People also seem to like the structure that has been developed for the
developer docs [3]. The question is how we get from here to there.
Looking at the existing platform-demos, it seems that, though there is
some excellent material there, much of it is not suitable for what we
are aiming for. The issues I can see are:

 * None of them use Glade, but instead have instructions for coding the UI.
 * Much of them are part of tutorial series (particularly the
JavaScript docs) - this means they don't fit well with topic based
"how do I...?" type documentation.
 * Basing the docs around tutorials for creating toy applications
isn't going to work if we are going to be targeting experienced
developers.

It seems that we are going to need new documentation, although maybe
there are some parts that we can recycle.

My suggestion for how to move forward has two parts.

For the main developer documentation, I have started a skeleton for
the new material, which I've pushed to a gnome-devel-docs branch [4].
(Please don't laugh at my Mallard skillz.) It includes quite a few
stubs, a number of which have notes included as comments. I can to
write some sections and can edit and guide (I have a pretty good view
from the design perspective, at least), but I'm no coder, so we'll
need contributors to help fill in the blanks. If anyone wants to help
write the new docs, that would be fantastic. It would also be good to
see if we could get an intern to help with this over the summer.

The other part is to create a set of beginners documentation (for
people who are new to programming). The existing platform-demos are
well suited to this and it shouldn't take too much work to re-purpose
them. We might want to start a separate branch for that effort.

How does that sound?

Allan

[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/beginner.png
[3] https://live.gnome.org/DocumentationProject/Tasks/DeveloperDocs#Developer_documentation_outline
[4] http://git.gnome.org/browse/gnome-devel-docs/log/?h=wip/reorganization