by I recently read “Documentation Writing for System Administrators” by Mark C. Langston.
In this post, I share a documenation set template written in DocBook and based on Mark’s book, some TPOSANA, and my own experience.
Version 1.0 of the template: http://www.verticalsysadmin.com/sa-site-doc/
DocBook sources: http://www.verticalsysadmin.com/sa-site-doc/sa-site-doc.docbook-xml.tar.gz
Why I chose DocBook:
A) Theoretically, I can output HTML and PDF, so I can have nice-looking soft-copy and hard-copy. (In practice, the PDF copy on my system does not look nice, but I can still print the Web version.) (I can also output in plain text).
B) I can consolidate my 3 current doc repos: the TWiki, the plain text files in one big directory, and the few Microsoft Word / Visio / Excel files on my Windows laptop. No more groping, “is it here? it it there? how about over here?”. Everything is in one place.
C) It looks a LOT cleaner than either the TWiki or the big directory full of text files! Finally, pretty docs!
If you are new to DocBook, here are some links to help you start:
0. http://en.wikipedia.org/wiki/Docbook
1. “What is DocBook?”, a one-page intro from Sagehill Enterprises, a DocBook consultancy:
http://www.sagehill.net/WhatIsDocbook.html
2. Eric Raymond’s DocBook Demystification HOWTO:
http://tldp.org/HOWTO/DocBook-Demystification-HOWTO
3. O’Reilly’s intro to DocBook for their authors: https://prod.oreilly.com/external/tools/docbook/docs/authoring/ (username: guest, leave password blank).
4. “Take My Advice: Don’t Learn XML” by Michael(tm) Smith
Explains how DocBook relates to XML, and gives a gentle intro to XML.
http://www.oreillynet.com/pub/a/oreilly/xml/news/dontlearn_0701.html
5. Some DocBook examples from The University of Edinburgh:
http://www.ogsadai.org.uk/documentation/ogsadai3.0/ogsadai3.0-axis/DocbookExamples.html
6. DocBook Lite – a subset of DocBook. Since DocBook Lite is a subset of DocBook, it’s a way to learn just enough DocBook to get going. I think this was originally an O’Reilly doc.
http://svn.collab.net/repos/svn/trunk/doc/tools/readme-dblite.html
Notes on my experience:
I had trouble getting going at first… On a CentOS 5.3 server, what finally worked for me, was using the CentOS “xmlto” package (“A tool for converting XML files to various formats.”) AND I had to specify version 4.4 of the DocBook XML – that’s what comes with CentOS. (Latest version of DocBook is 5, and a lot of DocBook examples that Google serves up have various other version numbers.)
How to create HTML output from book.xml, and put the output in the current directory: xmlto -o . xhtml book.xml
Turning to DocBook has improved the documentation scene at my employer, Deluxe Digital Cinema.
Let me know if you have any questions or comments.