Docbook is a great standard for technical documentation, it is easily converted into a range of formats (html, pdf etc) and while it can be styled according to taste; the layout is always familiar.
When I first started using Linux you had to read a lot of documentation - and it was mostly in docbook format so I got kind of used to it.
But it’s a rich standard - making it much harder to learn than HTML.
And there don’t seem to be many good editors for it.
- Templates available and can save as docbook - but for me it doesn’t produce valid documents
- This only ever supported a subset of the docbook standard, and whil it is quite nice to use docbook support seems to have faltered: it doesn’t work for me.
- The KDE web editor, provides some supportive utilities but is basically a syntax highlighted text editor in this role.
and there are others…
But nothing that really grabbed me…
until I found
I can use Eclipse to create the docs
It’s not a WYSIWIG editor, but it does know which elements can go where
Which softens the learning curve a lot.
and it does validate the document for you
Meaning that when I create the output - it just works!
I’ll post more when I’ve written some actual documentation.