+1 on this one Karan, your idea is gr8, as I've learned from this group, if there is a simpler solution for the same problem it is better to go with it :).
On 7/7/07, Dain Sundstrom <[EMAIL PROTECTED]> wrote:
How about a style guide for confluence based documentation? If find that if you tell people how you want something formatted, the normally follow it. For those that don't, we can just fix it for them (getting any content is more important than formatting :)). -dain On Jul 6, 2007, at 7:10 AM, Karan Malhi wrote: > Maybe its not a good idea. Formatting in xml would be a pain. Ignore > my last email :( > > On 7/6/07, Karan Malhi <[EMAIL PROTECTED]> wrote: >> 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 >> > > > -- > Karan Singh Malhi
-- Thanks - Mohammad Nour
