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,
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:
- 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.
- 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.
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,
On 08/22/2011 05:37 AM, Zane Bitter wrote:
It's probably worth mentioning that there are actually 3 audiences:
- People working on Matahari
- People writing apps against Matahari agents
- People writing their own agents
Agreed
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.
I like it!
On 08/19/2011 03:52 PM, Russell Bryant wrote:
- 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.
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/1536784ef210883709dafad8eb755ea3...
Thoughts?
On Tue, Aug 23, 2011 at 6:41 AM, Russell Bryant rbryant@redhat.com wrote:
On 08/19/2011 03:52 PM, Russell Bryant wrote:
- 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.
- 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/1536784ef210883709dafad8eb755ea3...
Thoughts?
I like it. Much better than my xslt conversion to text.
matahari@lists.fedorahosted.org