Hi All A minor correction. Allan Zarsuela also attended the meeting he was missed out of the attendee list (Sorry Allan!). I've updated the wiki page to include him.
Thanks Sharan On 2018/02/28 14:55:38, Michael Brohl <michael.br...@ecomify.de> wrote: > Hi Sharan, all, > > great stuff! I just want to thank everyone who attended the meeting and > put this together! > > I'll provide more feedback in the coming days. > > Regards, > > Michael > > > Am 28.02.18 um 15:43 schrieb Sharan Foga: > > Hi Everyone > > > > Thank you everyone who attended and please see below for the details I > > capturedÂ from the Skype call yesterday to help kickstart our > > documentation effort. > > > > *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 > > Â * 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 > > > > These were the main things I noted during the meeting so attendees, > > please feel free to let me know if there was anything I've missed or > > misunderstood. > > > > So for the people who didn't make the call - please feel free to > > provide your feedback and comments about the documentation approach we > > are wanting to take. > > > > Thanks > > Sharan > > > > > > > > > > >