Initial wiki page to help co-ordinate efforts of OFBiz Documentation team.

Documentation Roles

We are looking for volunteers in the following roles:

Writers / Authors

Reviewers / Proofreaders


NOTE: If you author an document, then you cannot be the proofreader


Team Members

The list below is the list of people who are taking part in the OFBiz documentation effort. Please add your details below if you would like to volunteer to help

Some people have volunteered to be mentors to other team members. If you would like a mentor, then please feel to approach any of the mentor volunteers.


NameConfluence IdLocation / TimezoneIn Skype GroupWilling to be a MentorDocumentation RoleMentor
Sharan FogaSharan FogaPrague, UTC+1YesYesAuthor, Proofreader, Editor 
Olivier HeintzOlivier HeintzFrance, UTC+1Yes Author 
Deepak NigamDeepak Nigam     
Tim BoydenTimothy BoydenBoston, UTC-4Yes Author, Proofreader 
Craig ParkerCraig BachelorMaine, UTC-5Yes  Sharan Foga
Arthur Marquez      
Swapnil M ManeSwapnil ManeIndia, UTC+5.5YesYesAuthor, Proofreader, Editor 
Michael BrohlMichael BrohlGermany, UTC+1YesYesAuthor, Proofreader, Editor 
Pranay PandeyPranay PandeyIndia, UTC+5.5Yes   
Aditya SharmaAditya Sharma     
Dennis Balkir Dennis BalkirGermany, UTC+1    
Akash JainAkash JainIndia, UTC+5.5Yes   
Tarun ThakurTarun Singh Thakur Yes   
Piotr Walesiak      
Giulio SperiGiulio SperiItaly, UTC+1    
Taher AlkhateebTaher AlkhateebKuwait, UTC +3YesTechnical Advice  
Vikram GuptaVikram GuptaDurban, SA, UTC+2    
Mauricio Tavares UTC+1    
Badar AliBadar Ali Yes  Swapnil Mane
Allan ZarsuelaAllan ZarsuelaUAE, UTC+4Yes Author, ProofreaderSharan Foga
Rebecca Johnson      
Benjamin JuglBenjamin JuglGermany, UTC+1    
Daniel Mejia    Spanish Translation, AuthorSharan Foga
Sanjay YadavSanjay YadavIndia, UTC+5.5
QA AdviceAuthor, Proofreader, Editor
 Wolfgang Rauchholz wp.rauchholz Barcelona, Spain, UTC +2  No Need a mentor  

Documentation Example : Writing Our First Guide Together

To get started we will be collaborating on writing the Human Resources guide together.

Human Resources Guide

Example structure for adoc files

Suggested Processes

Creating Documentation Jiras

  1. Create one main umbrella JIRA per module (eg Human Resources Guide JIRA Task List       )
  2. Create a JIRA for each of the individual documents that need to be written (e.g one for resumes.adoc, and another for human-resources-intro.adoc)
  3. JIRAs for individual documents will include the name of the document and either an template  (or a link to a template) to use for the document
  4. Link the individual JIRAs as sub tasks to the main umbrella JIRA

Assigning Yourself to Work on a JIRA

  1. A JIRA is available to be picked up and worked on if it does not have anyone assigned to it
  2. To pick up and start working on a JIRA, assign yourself to a JIRA that that do not have anyone assigned
  3. Click the "Start Progress" button and keep it like that as long as you are working on the task. This to let know others that you are actively working on the issue. Possibly click the "Stop Progress" button if you are pausing for this task. You may even unassign yourself if it's for a long period.

Writing the Documentation

  1. Each JIRA will have a template or a link to template for the write to use
  2. Writers will attach a text file to the JIRA ticket (NOTE: This will not be a patch file: Reasoning is that we do not want to lose contributors because they don't understand how to use subversion etc and create patches. The patch creation can be done at a later stage by the editors!)
  3. Writers will add a comment to the ticket that the file is ready for review  (Can we use any existing status to help?)

Reviewing Documentation

  1. Reviewers will check for any JIRA tickets ready for review (Not sure if we can use an existing status or rely on notification commnents. Perhaps when a document is started we already assign a reviewer who could also be a mentor....)
  2. Reviewers will read to ensure that the documentation is clear and readable (if they have any queries they can contact the writer)
  3. and check the written documentation and correct any minor grammatical errors
  4. Reviewers will then approve the text file as ready to be tested

Creating and Testing the Documentation

  1. Editors will then take the text file copy it into a working version of the Trunk
  2. They will copy the text file into the correct location in the documentation tree
  3. They will build the documentation and check that it the document appears correctly in the generated guide  (NOTE Maybe include a separate sub section here on the commands to use for building and the location of the generated documents: Use command ./gradlew generateOfbizDocumentation to generate the PDF and HTML files)
  4. They will create a patch file for the documentation and attach it to the individual JIRA (NOTE: This means that the individual JIRA will contain the original text file received from the writer and also a patch file with the intergrated written text)
  5. They will change the status that the ticket has been tested and is ready to be committed to the Trunk

Updating Documentation into the Trunk

  1. Editors that are committers will look for tickets that are ready to be committted and commit them into the trunk
  2. They will send notifications to the writers and reviewers that the document has been uploaded
  3. Editors will close the individual issue

Document Guidelines

Please refer to



We will be implementing a consistent naming standard for the documentation content files.

Example for Human Resources this will be as follows:

  1. humanres.adoc

    1. hr-intro.adoc

    2. hr-employee-evaluations.adoc

    3. hr-glossary.adoc

    4. hr-employee-positions.adoc

    5. hr-employees.adoc

    6. hr-employments.adoc

    7. hr-performance-review.adoc

    8. hr-positions.adoc

    9. hr-qualifications.adoc

    10. hr-recruitment.adoc

    11. hr-skills.adoc

    12. hr-resumes.adoc

    13. hr-training.adoc

    14. hr-leave.adoc

    15. hr-security.adoc

    16. hr-global-settings.adoc


So for the party manager this could be :

  1. party.adoc

    1. party-intro.adoc  (NOTE: Do we look at making the short code pty or something shorter than party????)

    2. party-glossary.adoc

    3. party-faq.adoc

    4. party-settings.adoc

    5. party-security.adoc

    6. etc.

This could give people a guideline for the base structure and you can immediately recognize what the file contains.

JIRA Issue Task List

Human Resource Guide 

Assigning Yourself A Jira Issue

The first step in the process is looking at the list of open documentation issues / sub tasks and choosing one to work on. Once you have decided to work on an issue, please assign it to yourself. You can do this by:

  1. Log into our OFBiz Jira issue tracker

  2. Locate the Jira issue you want to work on (Note: Unassigned means that no one is working on it)

  3. On the upper right hand side under the ‘People’ section you will see a link that says ‘Assign to me”

  4. Click the ‘Assign to me’ link and the issue will be assigned to yourself

You have now assigned yourself to work on an issue.







Initial  Team Setup Tasks

Next Steps:

Based on the discussions the proposed high level roadmap of next steps looks like this



This area is for work that the team will need to do but not yet!

Remove markdown files added to Birt in the following commit and incorporate it into the documentation framework:



This area is used for adding ideas and suggestions for brainstorming. If the idea or suggestion is move into the task list then it can be deleted from here. Also remove anything that is not relevant.

We can start, in the same time as other documents (Comment from Sharan Foga in response to this. Once we have done an example together so that everyone knows the process and how to work, then we can split off and do parallel work. Trying to do parallel work at the start, I think will cause problems until people are confident enough to work alone)

Documentation Reference for Contributors

What tools will they need to install and use

What process will they need to follow?

What templates will they need to use?

Where are examples of what the documentation should look like?

     At the beginning this page will be more a draft than a documentation but it can be help us to see if our documentation is usable by us (smile)

Doing a small modification on showHelp view to have a header with a link a the main manual (which have links to all the other files (wink))





Michael Brohl:

Sharan Foga



Which collaborations tools : jira, branch, github and with which rules

How the reader can search on multiple help files ?

How to be able to manage multi-language ? it's not a priority for ofbiz trunk but should be available on customer site (currently it's manage by content multi-language capabilities) 

Automatic translation for one file from docbook to asciidoc