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 <[email protected]> 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 > [email protected] > https://mail.gnome.org/mailman/listinfo/gnome-doc-list On Tue, Feb 26, 2013 at 7:24 PM, Allan Day <[email protected]> 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 > [email protected] > https://mail.gnome.org/mailman/listinfo/gnome-doc-list _______________________________________________ gnome-doc-list mailing list [email protected] https://mail.gnome.org/mailman/listinfo/gnome-doc-list
