ofbiz-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jacques Le Roux <jacques.le.r...@les7arts.com>
Subject Re: Notes from OFBiz Documentation Skype Call : 27th February 2018
Date Thu, 08 Mar 2018 10:51:36 GMT
Hi Sharan,

Thanks a lot for this information, much appreciated!

Though I don't feel yet the need to figure at https://cwiki.apache.org/confluence/display/OFBIZ/OFBiz+Documentation+Team,
of course as a long time 
help/wiki contributor I'll help as much as I can this ambitious and long term community effort.

I long ago created a Firefox group of 20+ tabs (URL links, Jira and wiki but not only) about
documentation. I'll try 1st to see if I can still find 
useful information there and will then contribute to the OFBiz+Documentation+Team  page


Le 28/02/2018 à 15:43, Sharan Foga a écrit :
> 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

View raw message