*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