On 08/19/2011 03:52 PM, Russell Bryant wrote:
2) Use the existing docbook manual (dev-manual in links above) as
the
base for the documentation. Move the existing content to be a "Writing
a new agent" chapter.
3) Create two new chapters:
- Chapter 1: Project Overview
Go over the project from a user's point of view. List the
agents that we have and at a high level, what they provide.
- Matahari APIs
The APIs we provide. The core of this chapter can be
automatically generated using an XSLT similar to doc/api.xsl.
Instead of transforming into a plain text format, it could
generate docbook XML.
Publican does a great job of rendering stellar looking documentation
from docbook. If we complete these steps, I think we'll have a great
manual that addresses our entire audience.
Here is a first pass on implementing what I described above.
http://www.russellbryant.net/matahari/en-US/html/
The Matahari APIs chapter is auto-generated. I haven't added the
overview chapter that I described above, yet. This will get better if
more and more documentation gets added to the schema files.
I probably need to go back and reconsider the details of some of the
docbook markup. The <section> depth gets kind of out of hand. However,
what's there gets the concept across.
The implementation can be found here:
https://github.com/russellb/matahari/commit/1536784ef210883709dafad8eb755...
Thoughts?
--
Russell Bryant