Hi Dave, This all sounds brilliant! More replies inline ;)
On Tue, 2006-10-17 at 15:50 +0200, Dave Neary wrote: > ...and getting them into print > > Hi all, > > I have talked to Shaun about this idea already, and Andy Oram (on CC) > has been very generous with his ideas up to this point. > > I have a dream. That when an engineer from a software developer goes to > developer.gnome.org that he will be in awe of the quality and > organisation of our developer documentation. That ISDs will choose our > platform because it's so damn easy to get started. That a GNOME guide > for ISDs will become a bestseller, and will generate some money for the > foundation. That through working with a professional editor, the GNOME > docs team gets bigger and better. library.gnome.org? Currently being worked on. It would be a good place to start (I believe there's going to be a "developer" section for e.g. the gtk+ tutorial, API references etc.). > > And then let's start all over again with user documentation. As part of Project Mallard (tm), a lot of the user docs would be rewritten (hopefully) in a more user-friendly form. If we could integrate that effort with this... > > I would like to ask the foundation to budget some money for editing work > to generate a great guide to the GNOME platform for ISDs. And I would > like to have the result of that work get into print, and end up on the > coffee-table of everyone on this list. > > So - that's my crazy idea. Thoughts? I like the idea. At the moment, the docs team is pretty understaffed and under-equipped though. Concentrating on developer docs in the first instance would be a really good idea. Though, I don't know where all the people would come from. While this dev doc stuff is going on, Project Mallard (tm) and associated techs [1] can begin to be put in place for when the user docs stuff can begin. > > > Andy has previously written on the importance of getting a feedback loop > with community written documentation: > http://www.onlamp.com/pub/a/onlamp/2006/07/06/rethinking-community-documentation.html > > He thinks that a first step in editing GNOME docs is to identify the > docs which we are going to use as a starting point, and then get some > quiz-type questions written which test understanding of the preceding > material. This will give us a baseline to measure the effectiveness of > the documentation, and allow us to focus our energy on where the docs > need improving/rewriting. > > Here's an example quiz: > Docs: http://volity.org/docs/ui-guide/ui-guide-html/guide.html > Quiz: http://volity.org/docs/ui-guide/proposed_quiz.html > > Our first job, then, is to come up with a list of documentation among > all the sources we have - from tutorials in the API docs, through the > ISD guide Shaun wrote and Zana Yuen's series of articles for RedHat > Magazine, old GNOME journal articles, tutorials, perhaps some bits of > GGAD - which we will use as the backbone of a great documentation set > for the GNOME platform. > > Then for each document or set of documents, we come up with quizzes > testing the knowledge. > > Then we put the quizzes in place, and provide some way to navigate > through the docs in a reasonably sane order. > > Then we improve the docs that need improving until we're ready to > publish, with feedback from a professional editor (Andy) along the way. > > Make no mistake, this is hard, it won't be done in 3 months, or even 6 > months, and you will all be sick of the project before it gets finished. > But here's the end result: > http://developer.gnome.org/doc/GGAD/bookcover.png (strike out Havoc's > name, insert your own). > > So - who's with me? I can help. Despite my (many) other projects. I'm not the greatest writer in the world (you should read my thesis sometime :), but I'm capable of writing at least first draft type stuff and testing / proof-reading / helping answer technical questions. I'd love to see a definitive "This is how to develop for GNOME and make it integrate well" type resource. Its one of the things we're really missing [2]. One thing I'd love to see is the project being cross-language (i.e. section on python, c, c++ etc.), if possible. Now all we need is a codename for the project [3]. Don [1] Including online doc-team status page which will make life easier in this regard. Maybe integrate quizzes with this and / or lib.g.o? [2] There are a few out there, but they all seem to be missing something for me [3] All projects should have codenames. And a world domination step. Though, that can come later. _______________________________________________ gnome-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gnome-doc-list
