Documentation markup experience

[Jim Campbell]

On Mon, Jun 7, 2010 at 5:48 AM, Milo Casagrande <milo at casagrande.name>wrote:

> Hi Daniel,
>
> what follows are my personal thoughts.
>
> 2010/5/31 Daniel Holbach <daniel.holbach at ubuntu.com>:
> > Hello everybody,
> >
> > there recently was a discussion about moving Packaging documentation
> > from the wiki back into some kind of documentation markup format.
>
> I'm glad to hear you would like to move that guide into a more
> structured markup format, translating it through the wiki is a tedious
> and complex process.
>
> > I'd like to hear from you what your experiences are with Documentation
> > markup, particularly from a contributions angle. Also: what is the
> > current state of the art? Is Mallard simple enough? Is it what we should
> > be using?
>
> I'm answering you this part before, and address the other points later.
>
> I'm only going to say something about what I consider the most common
> technology for writing documentation that we can use right now without
> much problems: Mallard and DocBook. There are also other technologies
> to write documentation, but or we don't have conversion tools for
> them, or are not that widespread in our communities.
>
> Mallard is what GNOME will be using more and more in the future. It is
> simple (syntax-speaking) than DocBook, it resembles more HTML to me.
> It is thought to create topic based documentation (like answering
> questions that users might ask) rather than books, but It can be used
> in other funny ways too.
>
> I think DocBook is kind of well known, since it has been around for
> quite some times: there are a lot of tools out there to convert
> DocBook into many forms, and there's a lot of OSS documentation
> written with it.
>
> > The reasons discussed were:
> >
> >  - generate offline documentation from it easily (.pdf, .html,
> >   package it etc.)
>
> With Mallard you can do HTML and Yelp can read it, so you can
> definitely package it (same with DocBook). There aren't (yet?)
> conversions tool to create PDF from Mallard though.
> With DocBook you can basically do all of the above, PDFs included (not
> directly, but the Ubuntu Doc team did that for some releases).
>
> >  - translatability
>
> You can translate both Mallard and DocBook documents, that's what
> GNOME is doing right now.
>
> >  - ability to file bugs on it
> >  - merge proposals
>
> As long as you have a bzr branch and a text editor, you can do all of
> the above with Mallard and DocBook.
>
> >  - better structure
>
> DocBook gives you the power to create books (divided into chapter),
> Mallard, as I said, is more topic based.
> Maybe you have to think a little bit more about the structure with
> Mallard than with DocBook (at least that's my own personal
> experience).
>
> Hope this might help you guys!
>
> Ciao.
>
> --
> Milo Casagrande <milo at casagrande.name>
>
>
> <https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc>
>

I agree with much of what Milo has written, and just wanted to add a few
things.  With regards to writing in Mallard, there is a GSoC student working
on an online Mallard editor this summer.  This could simplify the Mallard
authoring process even further, but we'll have to see how things turn out on
that project.

As for PDF output, Milo mentioned that there is no PDF option for Mallard at
the present time, but even if there were . . . FOP only provides for
relatively basic PDF formatting.   This affects DocBook PDF output, too.
LaTeX provides for excellent PDF output, but it suffers with regards to ease
of translation.  AFAIK, there are no automated tools in place to process
LaTeX docs, as they are not XML-based.

Mallard docs can reasonably be put into a format resembling a book.  You can
see an initial draft example of this at the Gitorious page for the Snake
Wrangling for Kids book.  http://gitorious.org/swfk

Jim
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20100607/4c3d01c3/attachment.html>