Initial wiki page to help co-ordinate efforts of OFBiz Documentation team.
We are looking for volunteers in the following roles:
Writers / Authors
Reviewers / Proofreaders
Editors
NOTE: If you author an document, then you cannot be the proofreader
Mentors
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.
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-4 | Yes | Author, Proofreader | ||
Craig Parker | Craig Bachelor | 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 | 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 |
To get started we will be collaborating on writing the Human Resources guide together.
Example structure for adoc files
Please refer to https://asciidoctor.org/docs/asciidoc-recommended-practices/
We will be implementing a consistent naming standard for the documentation content files.
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.
Human Resource Guide
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.
==========================
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: https://s.apache.org/eTqQ
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)
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 )
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.
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
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