I was thinking about how to have consistency in documentation for
openejb. What if we create a simple xml dtd/schema and author valid
xml documents. We could then apply standard xsl to it and use swizzle
confluence api to publish the doc. This way everybody can use their
favorite xml editor to author the docs. It might sound cumbersome, but
it will standardize the look and feel. Right now i see that some docs
have H2 for heading, while others have H3. Some are using numbered
bullets while others are not using bullets at all.
So here is the basic workflow:
1. Using openejb documentation dtd, author an xml doc
2. Create a JIRA for the documentation component in openejb and attach
this xml document
3. Somebody with enough rights runs a script which
-- applies xsl transformation to the doc
-- uses swizzle to upload the page
So, you might by asking , why not update the wiki directly. Well,
updating the wiki directly allows anybody to format the document the
way they want to and we lose the consistency.
An advantage to this approach is that you can checkout the xml doc,
work with it (without keeping the wiki open and worrying about saving
changes before you leave the page or accidentally close the browser) ,
and then submit a patch for it.
What do you think? Since you guys have tons of experience with OSS, is
there a better/simpler way to do it. The main focus here is
consistency throughout all documents and maintaining some control over
the table of contents , specially in the users and developers guide.
--
Karan Singh Malhi
