Automation of the documentation

[Jacques Le Roux <ja...@les7arts.com>]

Hi All,

I wrote this email 2 months ago but did not send it because in the meantime I wanted to think and answer to Pranay at https://s.apache.org/7Uyj (in 
relation with documentation history and svn capabilities about that)

Because of Michael's and Sharan's initiative I'm a bit late, so here is the email as I wrote it then.

------------------------------------------------------------------------------------------------------------------------------------------------------

After working on documenting the new Birt Flexible Report, I propose that we think about our documentation. It's good to have a documentation but only 
if it keeps updated, especially the technical part.

Obviously we have 2 types of users: end users and service providers. So roughly we have also 2 types of documentation, but let's put that aside for a 
moment.

We also have several locations for the documentation. At least: tooltips and labels in UI, embedded help, online help, readme files, main site and 
wiki. Did I miss something?

Some times ago Jacopo suggested that we keep, as much as possible, the documentation in the source.

I totally agree, because then we have the documentation near the place where the programs are, so they are/might-be more updated. And thanks to source 
control we have a sure history.
I know we have also an history in Confluence and we can consider Confluence stable at the ASF now (I remember the lost we had when we migrated to ASF 
Confluence). But there is not the same level of capability  for research.

For tooltips and labels (I mean more labels which explains things, but actually all somehow do, and in multi languages!) they are already part of the 
source, no worries, they should be up to date.

Readme files tend to be less up to date, but at least they are also part of the source. Recently Taher, with Gradle, put in Markdown for README.md 
files. I took advantage of this to almost automatically keep few wiki pages up to date.

Notably:

https://cwiki.apache.org/confluence/display/OFBIZ/From+Ant+to+Gradle

https://cwiki.apache.org/confluence/display/OFBIZ/Birt+Flexible+Reports

So this email to discuss the opportunity of putting less documentation outside of code and automate it to render in the wiki.

What do you think?

Jacques