On 19/08/11 21:52, Russell Bryant wrote:
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.
It's probably worth mentioning that there are actually 3 audiences:
1) People working on Matahari
2) People writing apps against Matahari agents
3) People writing their own agents
One of the things I want to do for group #3 is to create an example
agent outside of the Matahari project itself. A wiki page that lists all
the files (and their contents) you need to create an agent is cool, but
what's even better is a Git repo you can clone that already has
everything in it and you just change the names. This is on my to-do list.
---- 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,