...

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

...

Mentors

• • help documentation contributors
  • provide general background OFBiz help
  • provide examples documents
  • help contributors test their documentation

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.

Reference Information

Mentors Roles and Responsibilities

Highlight main tasks that mentors can help with

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?

...

Documentation Example : Writing Our First Guide Together

...

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. 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

Suggested Template Formatting

Document Guidelines

Please refer to https://asciidoctor.org/docs/asciidoc-recommended-practices/

Formatting

• Each .adoc file must contain the Apache license header (put between "//// license... ////")
• Recommendation say one sentence per line but are currently doing limiting lines to approx 80 characters... Not sure if are at the one sentence per line stage yet?Template will be plain text
• Filenames will be in lower case and extension will be .doc
• Text line width set at a maximum of 80 characters (??)
• First line in file will need to include '=' then one space, then the name of the section (e.g. = Timesheets)

• .adoc
• Section titles will use asymmetric atx style (e.g == This is an example of an Asymetric Section Title)
• When including another file using the 'include' directive, please ensure that there is a blank line between each include line (NOTE: From Taher - if we stack directives on top of each other asciidoctor might get confused especially if the headers in the different documents are a different levels)

Naming

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

• Each guide will be named after the component / moduel name (e.g. humanres.adoc, accounting.adoc, manufacturing.adoc, party.adoc etc).
• Lower level files that are in the include directory will include a prefix/shortname indicating the component name, separated by dashes (e.g hr-intro.adoc, hr-glossary.adoc...etc)
• Similar pages will have consistent naming. We will have several intro, glossary, FAQ, settings, security, so the naming format will be ([shortname]-intro, [shortname]-glossary, [shortname]-faq, [shortname]-settings, [shortname]-security etc.)

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.

==========================

...

•  Get the Proof of Concept (PoC) documentation framework written by Taher committed into the trunk (Done by Taher 8th March 2018)
•  Identify mentors who will be available to help less experienced documentation contributors (In progress. Michael, Sharan and Olivier have indicated they are available so far)
•  Use a wiki page to act as reference. (Done, this page is being used as that)
•   High level plan to show what is being done
•  a reference or FAQ for how to get started,
•  Details of the process that we want to follow and also a list of available mentors etc)
•  Define a Table of contents structure for each application (In Progress: Initial one is Human Resources)
•  Mentors will create the document structure within OFBiz (some files with data, some empty)
•  Create Jira tasks for the outstanding documentation work
•  Create some documentation and rules for 'how to write the documentation" (how to use asciidoc syntax for specifics situation, how to use asciidoc syntax for specifics situation
•   

TASKS IN WAITING

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: https://s.apache.org/eTqQ

BRAINSTORMING AREA

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

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.

...