On Mon, 2009-02-09 at 19:14 +0000, Alberto Ruiz wrote: > 2009/2/9 Shaun McCance <[email protected]>: > > 2) Provide better documentation for how to write documentation. > > The GDP Handbook is outdated and overwhelming. > > Quite true, as a matter of fact, I've been trying to learn how to > write documentation in the latests weeks. > > I know nothing about docbook and I like to consider myself sort of a > computer literate, and I'm telling you, my frustration could be used > as a reusable source of energy to power up a whole country at this > point. Why on earth is so hard to learn to create a document with a > few paragraphs and illustrations? > > > 3) Make documentation easier to write. Mallard can help. > > 4) Make it easier to see what documentation needs work. Pulse > > can help. > > What is Pulse? What is Mallard? How can they help? > > I've been thinking how hard would it be to have a very basic webkit > based editor that would convert the html it generates into docbook? > > Really, good documentation writers are most likely people with no > skills on SVN/DVCS/Docbook/XML whatsoever. We should provide a focused > editor supporting the very basic stuff to write a good GNOME document.
Pulse is project tracker. Among other things, it lists all of our documentation, including status information that can be encoded in the DocBook. I'm hoping to have a production server running by summer. There's a test instance running here: http://www.gnome.org/~shaunm/pulse/web/ Mallard is a new documentation format. You would write your documents in Mallard instead of DocBook. Points of interest: * Mallard does not assume you're writing a linear document. In fact, it assumes you are not. It provides navigation tools that are built around this assumption. * The vocabulary is considerably simpler than that of DocBook. The markup it provides is based on years of experience of what is actually useful in software documentation. * Mallard allows pages to be inserted into existing documents. This means that: - Portions of cross-module documents like the User Guide can be maintained alongside the things they describe. - Plugin documentation can be provided in a way that users can actually grok. - Downstream vendors can add information to our documentation without performing surgery. * Mallard's box model is sufficiently simple to write graphical editors and other tools. We had a summer of code project to create a graphical Mallard editor called FoieGras. -- Shaun _______________________________________________ desktop-devel-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/desktop-devel-list
