ofbiz-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sharan Foga <sha...@apache.org>
Subject Re: Notes from OFBiz Documentation Skype Call : 27th February 2018
Date Thu, 08 Mar 2018 07:58:44 GMT
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.brohl@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
> >
> >
> >
> >
> 
> 
> 

Mime
View raw message