Documentation markup experience

[Milo Casagrande]

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>