Re: Revamping the developer documentation

From: Marta Maria Casetti <mmcasetti gmail com>
To: Allan Day <allanpday gmail com>
Cc: GNOME Documentation <gnome-doc-list gnome org>
Subject: Re: Revamping the developer documentation
Date: Wed, 27 Feb 2013 14:09:07 +0100

 Hi,

It sounds great, and I would love to help with the new docs. I would
start by splitting the current Python GTK+ tutorial into a tutorial
for beginners (structured as the way the Tutorial for beginners is
now: a gradual path through the widgets with some theory; the pages
being a gradual building of a nice example) and something for more
experienced programmers (structured on the model of the "GTK+ widgets
sample code"; the pages being almost an API, but with a
medium-difficulty example to illustrate it). Then I would then revise
the Guitar Tuner and Image Viewer tutorials to make them a first
example of "10 minutes tutorials" (on GStreamer and GTK+,
respectively). I could do the same for the JavaScript tutorials,
especially if someone helps me (I am quite new to JavaScript), or i
could continue with Python and do something like what we have for GTK+
for some other library.

Best,
   Marta


On Tue, Feb 26, 2013 at 7:24 PM, Allan Day <allanpday gmail com> wrote:

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
_______________________________________________
gnome-doc-list mailing list
gnome-doc-list gnome org
https://mail.gnome.org/mailman/listinfo/gnome-doc-list


On Tue, Feb 26, 2013 at 7:24 PM, Allan Day <allanpday gmail com> wrote: