Notes from OFBiz Documentation Skype Call : 27th February 2018

[Sharan-F]

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

[Michael Brohl-3]

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

[Sharan Foga]

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 <[hidden email]> 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
> >
> >
> >
> >
>
>
>

[Jacques Le Roux]

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

Jacques


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