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