Documentation format

[stebe at mailbox.org]

Hi,

> "Robert J. Hansen" <rjh at sixdemonbag.org> hat am 6. Februar 2016 um 13:08
> geschrieben:
> 
> 
> Since I seem to have become the doyen of documentation, I figure I
> should ask: what markup language and/or output formats should we be
> pursuing for future documentation work?
> 
[...]
> Does anyone have any particular preferences?

I've been studying XML Schema (W3C standard, the official OASIS validation
standard is RELAX-NG) for some time now and have been playing around with
docbook5-xml, but I'm lacking practical application (i.e experience). I'm
still at it and will use it for a small installation and usage report for
the Nitrokey with which I am about to create a new gpg pub key and for
other docs I'd like to write. 
So, for now, I just can give you a semi-professional opinion.
Docbook5-xml is fully xml-compliant, supersedes the somewhat limited DTDs
by validating against XML schema (or, officially, Relax-NG) and is a
well-known and applied standard in technical documentation, especially in
computer science/industry, hard and soft. As far as output is concerned,
you can create (via XSLT, with xsltproc, for instance) other XML, HTML,
XHTML and plain text documents. Using the XSL-FO formatting language (and
an XSL-FO processor like Apache FOP) you can convert/render them to/as
PDF, text and Postscript and thus the output is very professional. The big
advantage of any standard or markup language based on XML, in particular,
is that XML is widely used as a universal data exchange format and an
ideal basis for single source publishing (one file, several output
formats).

Now to the question if you should use docbook5-xml. It depends. If you
want to use it only for a single document like the GNU Privacy Handbook, I
don't think that it would be worth learning it, as it requires too much
effort of studying (eh, in fact, I don't know if you are already using it
:-) compared to any other tool you might already know.
But if you plan to write a lot of documentation, or even if one has to use
it professionally (i.e. at work) I'd positively choose docbook5-xml.

Well, sorry for not being the old wise guy with 20 years of experience
(pretty old yes, wise hmm), but that's what I can tell you.

Cheers,

Stebe