...
- 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
...
Name | Confluence Id | Location / Timezone | In Skype Group | Willing to be a Mentor | Documentation Role | Mentor | |
---|---|---|---|---|---|---|---|
Sharan Foga | Sharan Foga | Prague, UTC+1 | Yes | Yes | Author, Proofreader, Editor | ||
Olivier Heintz | Olivier Heintz | France, UTC+1 | Yes | Author | |||
Deepak Nigam | Deepak Nigam | ||||||
Tim Boyden | Timothy Boyden | Boston, UTC-54 | Yes | Author, Proofreader | |||
Craig Parker | Craig Bachelor | EST (NY time), which is -5:00 GMT I think.Maine, UTC-5 | Yes | Sharan Foga | |||
Arthur Marquez | |||||||
Swapnil M Mane | Swapnil Mane | India, UTC+5.5 | Yes | Yes | Author, Proofreader, Editor | ||
Michael Brohl | Michael Brohl | Germany, UTC+1 | Yes | Yes | Author, Proofreader, Editor | ||
Pranay Pandey | Pranay Pandey | India, UTC+5.5 | Yes | ||||
Aditya Sharma | Aditya Sharma | ||||||
Dennis Balkir | Dennis Balkir | Germany, UTC+1 | |||||
Akash Jain | Akash Jain | India, UTC+5.5 | Yes | ||||
Tarun Thakur | Tarun Singh Thakur | Yes | |||||
Piotr Walesiak | |||||||
Giulio Speri | Giulio Speri | Italy, UTC+1 | |||||
Taher Alkhateeb | Taher Alkhateeb | Kuwait, UTC +3 | Yes | Technical Advice | |||
Vikram Gupta | Vikram Gupta | Durban, SA, UTC+2 | |||||
Mauricio Tavares | UTC+1 | ||||||
Badar Ali | Badar Ali | Yes | Swapnil Mane | ||||
Allan Zarsuela | Allan Zarsuela | UAE, UTC+4 | Yes | Author, Proofreader | Sharan Foga | ||
Rebecca Johnson | |||||||
Benjamin Jugl | Benjamin Jugl | Germany, UTC+1 | |||||
Daniel Mejia |
Documentation Example : Writing Our First Guide Together
To get started we will be collaborating on writing the Human Resources guide together.
Example structure for adoc files
Suggested Processes
Creating Documentation Jiras
- Create one main umbrella JIRA per module (eg Human Resources Guide JIRA Task List
)Jira server ASF JIRA serverId 5aa69414-a9e9-3523-82ec-879b028fb15b key OFBIZ-10251 - 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)
- 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
- Link the individual JIRAs as sub tasks to the main umbrella JIRA
Assigning Yourself to Work on a JIRA
- A JIRA is available to be picked up and worked on if it does not have anyone assigned to it
- To pick up and start working on a JIRA, assign yourself to a JIRA that that do not have anyone assigned
Writing the Documentation
- Each JIRA will have a template or a link to template for the write to use
- 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!)
- 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
- 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....)
- Reviewers will read to ensure that the documentation is clear and readable (if they have any queries they can contact the writer)
- and check the written documentation and correct any minor grammatical errors
- Reviewers will then approve the text file as ready to be tested
Creating and Testing the Documentation
- Editors will then take the text file copy it into a working version of the Trunk
- They will copy the text file into the correct location in the documentation tree
- 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)
- 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)
- 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
- Editors that are committers will look for tickets that are ready to be committted and commit them into the trunk
- They will send notifications to the writers and reviewers that the document has been uploaded
- Editors will close the individual issue
Document Guidelines
Formatting
- 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)
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:
humanres.adoc
hr-intro.adoc
hr-employee-evaluations.adoc
hr-glossary.adoc
hr-employee-positions.adoc
hr-employees.adoc
hr-employments.adoc
hr-performance-review.adoc
hr-positions.adoc
hr-qualifications.adoc
hr-recruitment.adoc
hr-skills.adoc
hr-resumes.adoc
hr-training.adoc
hr-leave.adoc
hr-security.adoc
hr-global-settings.adoc
So for the party manager this could be :
party.adoc
party-intro.adoc (NOTE: Do we look at making the short code pty or something shorter than party????)
party-glossary.adoc
party-faq.adoc
party-settings.adoc
party-security.adoc
etc.
This could give people a guideline for the base structure and you can immediately recognize what the file contains.
JIRA Issue Task List
Spanish Translation, Author | Sharan Foga | |||||
Sanjay Yadav | Sanjay Yadav | India, UTC+5.5 | QA Advice | Author, 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.
Example structure for adoc files
Suggested Processes
Creating Documentation Jiras
- Create one main umbrella JIRA per module (eg Human Resources Guide JIRA Task List
)Jira server ASF JIRA serverId 5aa69414-a9e9-3523-82ec-879b028fb15b key OFBIZ-10251 - 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)
- 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
- Link the individual JIRAs as sub tasks to the main umbrella JIRA
Assigning Yourself to Work on a JIRA
- A JIRA is available to be picked up and worked on if it does not have anyone assigned to it
- To pick up and start working on a JIRA, assign yourself to a JIRA that that do not have anyone assigned
- 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
- Each JIRA will have a template or a link to template for the write to use
- 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!)
- 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
- 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....)
- Reviewers will read to ensure that the documentation is clear and readable (if they have any queries they can contact the writer)
- and check the written documentation and correct any minor grammatical errors
- Reviewers will then approve the text file as ready to be tested
Creating and Testing the Documentation
- Editors will then take the text file copy it into a working version of the Trunk
- They will copy the text file into the correct location in the documentation tree
- 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)
- 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)
- 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
- Editors that are committers will look for tickets that are ready to be committted and commit them into the trunk
- They will send notifications to the writers and reviewers that the document has been uploaded
- Editors will close the individual issue
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?
- Filenames will be in lower case and extension will be .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:
humanres.adoc
hr-intro.adoc
hr-employee-evaluations.adoc
hr-glossary.adoc
hr-employee-positions.adoc
hr-employees.adoc
hr-employments.adoc
hr-performance-review.adoc
hr-positions.adoc
hr-qualifications.adoc
hr-recruitment.adoc
hr-skills.adoc
hr-resumes.adoc
hr-training.adoc
hr-leave.adoc
hr-security.adoc
hr-global-settings.adoc
So for the party manager this could be :
party.adoc
party-intro.adoc (NOTE: Do we look at making the short code pty or something shorter than party????)
party-glossary.adoc
party-faq.adoc
party-settings.adoc
party-security.adoc
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
Jira | ||||||
---|---|---|---|---|---|---|
|
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:
Log into our OFBiz Jira issue tracker
Locate the Jira issue you want to work on (Note: Unassigned means that no one is working on it)
On the upper right hand side under the ‘People’ section you will see a link that says ‘Assign to me”
Click the ‘Assign to me’ link and the issue will be assigned to yourself
You have now assigned yourself to work on an issue.
Human Resource Guide Jira
==========================
...
- 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
...