Greetings,
Documentation is absolutely critical for the success of our project. I've spent some time thinking about documentation for our users. Here is my proposal for the direction we should take.
---- Existing Documentation
First, it's worth looking at what we have so far. We have 2 documentation sets up and running so far:
a) http://matahariproject.org/dev-manual/ b) http://clusterlabs.org/doxygen/matahari/1f5dfea/index.html
There is not necessarily overlap between the content, but the audience for these two sets of documentation is the same: people working on matahari itself. If all goes as planned, there will be a much larger audience that needs documentation from us: those that write applications against the agents we provide.
---- To-Do
The gap in the documentation we have today is for the users of the matahari agents. I don't think it's in the scope of our project to document how to write applications using QMF or DBus in general. However, we can help fill in the gaps in this area as we see fit. One of the biggest things we can do here is provide good examples in our project.
It is definitely within the scope of our project to make it quick and easy to figure out the details of the APIs we provide.
Andrew has done some nice work demonstrating how an XSLT can be used to transform the schema files into another format. Take a look:
$ xsltproc doc/api.xsl src/host/schema.xml
I think we can take this, run with it, and end up with some great docs. Proposed steps:
1) Continue adding documentation in the schema. For some items, the schema already provides a place to include a description. For more verbose descriptions of methods, etc., we can place it in an XML comment above the entry in the schema. The host schema has some examples of this and the existing XSLT demonstrates how we can grab the contents of the comment. We should go through and add documentation for _everything_ in the schemas.
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.
As always, feedback welcome.
Thanks,