Child pages
  • OFBiz Documentation Skype Call: February 2018

Access to add and change pages is restricted. See: https://cwiki.apache.org/confluence/display/OFBIZ/Wiki+access

Skip to end of metadata
Go to start of metadata
*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
  • No labels