Page History

...

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

Image Removed

Suggested Processes

Creating Documentation Jiras

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

Image Added

Suggested Processes

Creating Documentation Jiras

1. Create one main umbrella JIRA per module (eg Human Resources Guide JIRA Task List   

   Jira
   server ASF JIRA serverId 5aa69414-a9e9-3523-82ec-879b028fb15b

   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

      )
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

...

1. A JIRA is available to be picked up and worked on if it does 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 to itTo 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

Document Guidelines

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

Formatting

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?One sentence per line
• 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.

...

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

...