qpid-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jonathan Robie <jonathan.ro...@redhat.com>
Subject Re: Move documentation to svn / DocBook?
Date Wed, 02 Dec 2009 16:14:53 GMT
On 12/01/2009 08:20 PM, Aidan Skinner wrote:
> The only word of advice I'll offer, since it didn't succeed before, is
> that it should be done quickly since it's a moving target. If I had
> the time to try again, I might pick a hard cut off date and Just Do
> It.
>    

I think one way to make the transition easier is to work bottom up, 
picking a set of documents to work on, and doing that in DocBook. I'd 
separate the following:


1. Documents - in Docbook

The documentation page is a good place to start looking for candidate 
documents:

http://qpid.apache.org/documentation.html

At first blush, I'd like to see one document for each of the following:

* AMQP Messaging Broker (C++ Implementation)
* AMQP Messaging Broker (Java Implementation)
* AMQP Client Programming Tutorials (one per language, using the new 
API, references the API docs)

On the C++ / Python side, the new client API tutorials seem like a 
logical candidate for the first documents, and I'm likely to start there.

I think the easiest thing to do here is to use the standard Docbook 
stylesheets, create some template example files, showing how to mark up 
a chapter, and start writing some documents. I have little experience 
with Forrest for this kind of thing, but I have read some reviews that 
suggest pure DocBook is much more mature for this kind of documentation, 
and there are lots of tools for DocBook.


2. Main page of the site - raw HTML?

The main page generally does not change much, and graphical presentation 
is important here. Raw HTML gives us a lot of control. I would be 
inclined to simpy write a page in HTML for this.

I think this is orthogonal to the documentation per se, and should be 
done as a separate project.

3. Navigation pages - Forrest? raw HTML?

We have a small number of navigational pages that get people to other 
content. Again, raw HTML can work well for this.


4. Simple HTML pages not intended for other formats

We have pages, like the "Getting Started" page, which probably will be 
presented only in HTML. It's easy enough to write them in DocBook and 
transform them to HTML. We probably need to version this content along 
with the rest of the site.

Would Forrest be helpful for 3 and 4? What advantages would it bring?

Jonathan

---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project:      http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org


Mime
View raw message