Re: quo vadis, docs

[Shaun McCance <shaunm gnome org>]

On Mon, 2009-02-09 at 19:14 +0000, Alberto Ruiz wrote:
> 2009/2/9 Shaun McCance <shaunm gnome org>:
> > 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