OFBiz Documentation Team

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

Example macro for potential roadmap planner.

Team Members

Please add your details below if you would like to volunteer to help

Deepak Nigam

UTC+1

Initial  Team Setup Tasks

• Ensure all team members have ICLAs filed (Started 13/02/18 In progress) 
• Collect all Confluence and JIRA ids and ensure contributor permissions are setup (Started 13/02/18 and in progress)
• Skype call to talk about how to get started :

Brainstorming Ideas

How to get started with planning and organisation?

• Define a table of contents of the documentation that we want to produce and use it as the document structure within OFBiz.
• Define target (ordered) for documentation reader and usage (contextual help screen or function or component or "README" by component, function, process, or book or ...)

We want documents to be small and focussed on one topic (this will make it more re-usable).

We don't want to just copy and paste what we already have

We have a complete HR manual - could we use it as a first set of documents  to all work on together?

We can start, in the same time as other documents, the "how to write documentation" page/section to be able to  share

• how to use asciidoc syntax for specifics situation
• rules for trying to be homogeneous 

     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

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 )

Michael Brohl:

• We should set up a small documentation quality team which is responsible that the documentation send in by contributors is of good quality, consistent and (mostly) error free. This team should also propose the structure of the documentation and maybe add the empty .adoc files and includes to lead the way for contributors.
• It could also be a good idea to track who is working on a piece of documentation to avoid double work and encourage collaboration between contributors interested in the same topic(s). I think this might be Jira with a main task containing the main "rules" of documentation and several subtasks for each topic.
• I suggest to have also a process to move documentation from the Wiki to the documentation in the repository. We should make sure that we do not have different documentation in both places. If someone is working on a topic he also could search the Wiki for it and try to merge/move it where applicable. Moved/merged documentation from the Wiki should then be moved to an adoc Attic until everthing is cleared and the community agrees to remove it from the Wiki.
• We should also define which contents should be in the repository and what the Wiki should contain or be linked to.

Sharan Foga

• To get started we need to focus on co-ordination, structure and organisation (we have a lot of people wanting to contribute but their efforts need to be co-ordinated
• We need a visual high level plan (see example roadmap above) so that everyone can quickly see progress and main milestones
• Need to define the scope of the effort (maybe do this by saying what we are not going to do??, eg. not an FAQ, not a tutorial, not a use case, not a cookbook) so will be feature documentation (i.e. describing what we have available)
• Look at using JIRA as main co-ordination and tracking tool. We could look at usin a new label eg 'documentation' in conjunction with the existing components. Maybe update workflow to have a new QA status 
• Assumption is that the work will be done in the trunk (since 17.12 branch already created) and will be part of the 18.xx branch. Do we look at backporting to 17.12 ???
• Ways to get started working together : Let's all work together on one component (suggest HR since a complete HR manual already exists. It will need review and maybe rewrite but the main content is already there. Each person can be allocated an area and be responsible for submitting a patch
  
  

Questions

How to test a process documentation, related (or not) with demo data ? (where to put source asccidoc files, how to arrive on it)

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) 

Tasks / actions available

Automatic translation for one file from docbook to asciidoc