*Skype Call to Kickstart OFBiz Documentation Effort*
*Date*: 27th February 2018 at 14.00 (UTC+1)
_*Agenda*_
* Introductions
* Technical Environment Overview
* Collaboration Environment
* Next Steps and Actions
_*Introductions*_
* 8 people attended the call.- Olivier Heintz, Tim Boyden, Arthur
Marquez, Tarun Thakur, Bader Ali, Taher Alkhateeb, Jacopo
Cappellato, Sharan Foga, Allan Zarsuela
* Main objective were to discuss how to kick off the OFBiz
Documentation effort
_*General Overview*_
* We went through a bit of an overview of the project and the
background regarding OFBiz documentation.
* Initially the project had implemented docbook but this used XML and
had a large complex vocabulary, that made it not easy for people to
use.It also wasn't very adaptable as a generic documentation tool
* After many discussions on the dev list we decided to adopt asciidoc
because it was a lot simpler to use.
o Writing asciidoc is a lot like normal writing in English, which
will allow people with little or no technical knowledge the
ability to contribute
o there was already a lot of documentation about how to use it
o it has different publishing options (html, PDF etc) and so can
in future be integrated with our online help
* The purpose of the documentation project is divided into 3 areas
o to provide comprehensive documentation for all of OFBiz
o to be a tool for one source publishing to multiple outputs
o to integrate with the online help
* Everyone that can help with this effort will add value. We have a
variety of people from different backgrounds that will make the
documentation richer and based on practical experience.
*_General Guidelines_*
* Want to try and avoid copy and paste patterns and make documentation
modular, so that we write it once and re-use in many places
http://www.writethedocs.org/guide/
* Focus on more topic based documentation to help users achieve
something so they can get started quickly
https://en.wikipedia.org/wiki/Topic-based_authoring
* Need to keep an open mind as this documentation effort will be an
evolution. We wont get it right first time and there will be several
iterations where we change content multiple times
* Documentation can't work without content so our first key focus
should be to get as much content into the framework as possible
(knowing that it maybe updated and evolve as we go)
* The PoC documentation framework that we will use is neutral so we
can make the documentation as detailed as we want
* The documentation will be in English only at this stage. Once we
have a completed English manual, we can look at other languages and
perhaps these can be provided via a plugin...
* Put together some getting started guidelines that will be a
reference. It could include roles and responsibilities and also an
overview of the end to end process flow to get some documentation
submitted
_*Design*_
* Documentation that we will be working on writing will be essentially
2 top level parts
o Framework Guide (technical / developer)
o Core Applications (user)
* Documentation for plugins will be managed separately and so each
plugin will have its own documentation. (NOTE: this means that each
specialpurpose application will have its own)
* We can make use of a structure of hidden vs published documents. We
can create multiple modular topic related files in a hidden
directory and then include whatever topics we need in the published
document
* The header offset option allows us to publish each application as a
separate guide (e.g accounting guide, manufacturing etc) rather than
all of the application
* We can look at other published guides to help us see what good
documentation looks like e.g https://gradle.org/docs/
*_Documentation Tools_*
* We can use our existing JIRA to track the documentation work. This
means that people can pick up a Jira ticket to work on.
* Some tools were suggested for people who wanted to start writing
* asciidocfx : https://asciidocfx.com
* eclipse plugin for asciidoc :
http://marketplace.eclipse.org/content/asciidoc-tools
* Also many modern editors will also be OK (e.g. atom etc)
_*Mentoring*_
* We discussed the idea of providing mentors for people to get
started. Some people are new to OFBiz and need some guidance to help
them get going.
* Suggestion is that the more experienced OFBiz people volunteer to
help others get up to speed
* Mentors can create some example documents for new contributors to
use or learn from. They can also create a documentation structure
for applications with empty files that contributors can work on to
complete
_*Suggested Process*_
* Work will be done using the Trunk (will probably need to move
communication to the dev list)
* Submitting documentation will be a two part process - researching
and writing, and then QA to check what has been written
* During the writing phase we will need to locate all existing
documentation about a topic (from the wiki etc) and consolidate it
into the new document
* Submit the written documentation for QA (and move all existing to
the Attic, so that we clean as we go)
* If the document passes QA it can be committed (so we will need
active involvement from the mentors and other committers)
_*Ideas / Challenges*_
* We have a lot of documentation in the README.md so how do we move or
integrate it into the documentation we are about to write?
* What will we display for the online help as it won't be initially
integrated?
* Do we look at asciidoctorj
(http://asciidoctor.org/docs/asciidoctorj/) for future integration
with online system
* Out of the box the OFBiz applications are generic, so maybe people
will be more comfortable writing documentation for a set of business
processes they know (e.g. Retail) because it could be easier to
describe
* Do we include industry specific documentation in an appendix?
* Start with everyone working on a small document to get an idea of
the process
_*Next Steps
*_
Based on the discussions the proposed high level roadmap of next steps
looks like this:
* Get the Proof of Concept (PoC) documentation framework written by
Taher committed into the trunk
* Identify mentors who will be available to help less experienced
documentation contributors
* Use a wiki page to act as reference. It can contain a 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 (We can
try to keep them in a similar standard structure)
* Mentors will create the document structure within OFBiz (some files
with data, some empty)
* Create Jira tasks for the outstanding documentation work
Access to add and change pages is restricted. See: https://cwiki.apache.org/confluence/display/OFBIZ/Wiki+access
Overview
Content Tools
Apps