[Discussion] documentation framework for OFBiz

[Gil Portenseigne]

:D indeed !

I will try it out tonight !

Gil


On 15/01/2018 09:27, Taher Alkhateeb wrote:

> Hi Gil,
>
> There is nothing simpler than linking docs together. Code snippet:
>
> include::relative/path/to/document/document-name.adoc[]
>
> Wow right :)
>
> On Mon, Jan 15, 2018 at 11:15 AM, gil portenseigne
> <[hidden email]> wrote:
>> Hello Taher,
>>
>> I did try your patch and played a bit with the asciidoctor integration you
>> provide, this week-end.
>>
>> That's quite simple, i like it, i will play a bit more with it to find the
>> good way to links docs files between them.
>>
>> Thanks !
>>
>> Gil
>>
>>
>>
>> On 12/01/2018 17:36, Taher Alkhateeb wrote:
>>> Hello everyone,
>>>
>>> Sorry for the delay on my part, I got a little preoccupied. Anyway, I
>>> have a small patch in [1] that provides the PoC for integrating
>>> asciidoctor with OFBiz. I also provided in the the JIRA [1]
>>> instructions on how to run it. Essentially, this allows you to create
>>> documentation for any component by simply creating a src/docs/asciidoc
>>> directory and putting files inside.
>>>
>>> This solution is flexible and allows us to build bigger designs on top
>>> of it. Please review it and tell me if you like the general design.
>>>
>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>>>
>>> On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
>>> <[hidden email]> wrote:
>>>> Hello Folks,
>>>>
>>>> We've had this discussion multiple times in the past, but I think I
>>>> have a more concrete idea this time for solving this problem. In the
>>>> past few weeks we've been working internally in Pythys to figure out
>>>> the best way to write and distribute documentation, and I think most
>>>> of that is applicable to OFBiz.
>>>>
>>>> In a nutshell, here is the idea (practically) for how to proceed:
>>>>
>>>> - The documentation language to use is Asciidoc
>>>> - The documentation tool is Asciidoctor
>>>> - Publishing happens through Gradle using the asciidoctor gradle
>>>> plugin (not the OFBiz framework or anything else).
>>>> - The only place where we write documentation is inside the code base
>>>> - Every component contains its own documentation
>>>> - General documentation goes to either a standalone directory or a
>>>> generic component like common or base
>>>> - As much as possible, documentation files are small and focused on
>>>> one topic. And then other longer documents are constructed from these
>>>> snippets of documentation.
>>>> - We publish to all formats including PDF for users, or HTML for
>>>> embedded help and wiki pages. So OFBiz does not parse docbook for its
>>>> help system, instead it just renders generated HTML.
>>>>
>>>> As I've worked extensively with Asciidoc I find it easy to pickup
>>>> (like markdown) but also modular (like docbook and dita). It's also
>>>> neat that you can sprinkle variables all around in your document so
>>>> that update is no longer a painful grepping process.
>>>>
>>>> Would love to hear your thoughts on this.
>>>>
>>>> Cheers,
>>>>
>>>> Taher Alkhateeb
>>

[Sharan Foga]

Hi Taher

Great work! I tried it out and found it simple and easy to use (and write!). When can we start writing ? :-)

I was thinking to start with basic descriptions of each of the applications, then see how it evolves from there. We can maybe recover some documentation content from various sources including our existing online help system and the wiki.

The documentation structure will maybe need some thought, and we may need to sort out some common template or guidelines around it.

Thanks
Sharan

On 2018-01-14 12:33, "Sharan Foga"<[hidden email]> wrote:

> Excellent news Taher!
>
> Thanks very much for your effort on this. I'll aim to try it out this week and come back with any feedback.
>
> Thanks
> Sharan
>
> On 2018-01-12 17:36, Taher Alkhateeb <[hidden email]> wrote:
> > Hello everyone,
> >
> > Sorry for the delay on my part, I got a little preoccupied. Anyway, I
> > have a small patch in [1] that provides the PoC for integrating
> > asciidoctor with OFBiz. I also provided in the the JIRA [1]
> > instructions on how to run it. Essentially, this allows you to create
> > documentation for any component by simply creating a src/docs/asciidoc
> > directory and putting files inside.
> >
> > This solution is flexible and allows us to build bigger designs on top
> > of it. Please review it and tell me if you like the general design.
> >
> > [1] https://issues.apache.org/jira/browse/OFBIZ-9873
> >
> > On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
> > <[hidden email]> wrote:
> > > Hello Folks,
> > >
> > > We've had this discussion multiple times in the past, but I think I
> > > have a more concrete idea this time for solving this problem. In the
> > > past few weeks we've been working internally in Pythys to figure out
> > > the best way to write and distribute documentation, and I think most
> > > of that is applicable to OFBiz.
> > >
> > > In a nutshell, here is the idea (practically) for how to proceed:
> > >
> > > - The documentation language to use is Asciidoc
> > > - The documentation tool is Asciidoctor
> > > - Publishing happens through Gradle using the asciidoctor gradle
> > > plugin (not the OFBiz framework or anything else).
> > > - The only place where we write documentation is inside the code base
> > > - Every component contains its own documentation
> > > - General documentation goes to either a standalone directory or a
> > > generic component like common or base
> > > - As much as possible, documentation files are small and focused on
> > > one topic. And then other longer documents are constructed from these
> > > snippets of documentation.
> > > - We publish to all formats including PDF for users, or HTML for
> > > embedded help and wiki pages. So OFBiz does not parse docbook for its
> > > help system, instead it just renders generated HTML.
> > >
> > > As I've worked extensively with Asciidoc I find it easy to pickup
> > > (like markdown) but also modular (like docbook and dita). It's also
> > > neat that you can sprinkle variables all around in your document so
> > > that update is no longer a painful grepping process.
> > >
> > > Would love to hear your thoughts on this.
> > >
> > > Cheers,
> > >
> > > Taher Alkhateeb
> >
>

[Craig Parker]

I think the doc structure ought to mirror the menu in the software, or
are you talking about how a doc itself is laid out?


On 01/17/2018 09:25 AM, Sharan Foga wrote:

> Hi Taher
>
> Great work! I tried it out and found it simple and easy to use (and write!). When can we start writing ? :-)
>
> I was thinking to start with basic descriptions of each of the applications, then see how it evolves from there. We can maybe recover some documentation content from various sources including our existing online help system and the wiki.
>
> The documentation structure will maybe need some thought, and we may need to sort out some common template or guidelines around it.
>
> Thanks
> Sharan
>
> On 2018-01-14 12:33, "Sharan Foga"<[hidden email]> wrote:
>> Excellent news Taher!
>>
>> Thanks very much for your effort on this. I'll aim to try it out this week and come back with any feedback.
>>
>> Thanks
>> Sharan
>>
>> On 2018-01-12 17:36, Taher Alkhateeb <[hidden email]> wrote:
>>> Hello everyone,
>>>
>>> Sorry for the delay on my part, I got a little preoccupied. Anyway, I
>>> have a small patch in [1] that provides the PoC for integrating
>>> asciidoctor with OFBiz. I also provided in the the JIRA [1]
>>> instructions on how to run it. Essentially, this allows you to create
>>> documentation for any component by simply creating a src/docs/asciidoc
>>> directory and putting files inside.
>>>
>>> This solution is flexible and allows us to build bigger designs on top
>>> of it. Please review it and tell me if you like the general design.
>>>
>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>>>
>>> On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
>>> <[hidden email]> wrote:
>>>> Hello Folks,
>>>>
>>>> We've had this discussion multiple times in the past, but I think I
>>>> have a more concrete idea this time for solving this problem. In the
>>>> past few weeks we've been working internally in Pythys to figure out
>>>> the best way to write and distribute documentation, and I think most
>>>> of that is applicable to OFBiz.
>>>>
>>>> In a nutshell, here is the idea (practically) for how to proceed:
>>>>
>>>> - The documentation language to use is Asciidoc
>>>> - The documentation tool is Asciidoctor
>>>> - Publishing happens through Gradle using the asciidoctor gradle
>>>> plugin (not the OFBiz framework or anything else).
>>>> - The only place where we write documentation is inside the code base
>>>> - Every component contains its own documentation
>>>> - General documentation goes to either a standalone directory or a
>>>> generic component like common or base
>>>> - As much as possible, documentation files are small and focused on
>>>> one topic. And then other longer documents are constructed from these
>>>> snippets of documentation.
>>>> - We publish to all formats including PDF for users, or HTML for
>>>> embedded help and wiki pages. So OFBiz does not parse docbook for its
>>>> help system, instead it just renders generated HTML.
>>>>
>>>> As I've worked extensively with Asciidoc I find it easy to pickup
>>>> (like markdown) but also modular (like docbook and dita). It's also
>>>> neat that you can sprinkle variables all around in your document so
>>>> that update is no longer a painful grepping process.
>>>>
>>>> Would love to hear your thoughts on this.
>>>>
>>>> Cheers,
>>>>
>>>> Taher Alkhateeb

[taher]

So I have thought of a few ways to implement our documentation
structure and I would like to share my ideas with everyone to see what
you prefer to go with. Here goes:

- First, let's categorize documentation as:
  - component-specific
  - general documentation
- component specific documentation lives inside the component in
"/src/docs/asciidoc". It is a self contained piece of documentation.
- Every component has only _one_ publishable document. There is a
methodology in asciidoctor to denote public and private documents.
private documents will not be published but only included in other
documents. This way we can make a modular documentation for each
component while publishing only one output.
- general documentation (i'm still scratching my head over this one)
could be placed maybe in framework/base. What it does is explain high
level information about the framework and explain general conceptual
principles of how things work.
- We can combine the entire documentation of everything (framework +
applications) in a single document that references all the other
documents and maybe we can place it at the top-level directory and
call it something like ofbiz-documentation.adoc
- Plugins are not included in the full documentation, they are self
contained and are not part of the _big_ published manual. instead each
plugin has its own mini manual.
- We declare three gradle tasks similar to the below:
  - "./gradlew publishComponentDocs": publish documentation for a
specific component / plugin which requires a componentName flag.
  - "./gradlew publishAllComponentsDocs": publish documentation for
all components / plugins
  - "./gradlew publishOfbizDocs": publish the master documentation
manual that combines everything.

This is a brain dump so I leave it to you fine folks to refine the
ideas and decide where we should go.

Cheers,

Taher Alkhateeb

On Wed, Jan 17, 2018 at 6:08 PM, Craig Parker <[hidden email]> wrote:

> I think the doc structure ought to mirror the menu in the software, or are
> you talking about how a doc itself is laid out?
>
>
>
> On 01/17/2018 09:25 AM, Sharan Foga wrote:
>>
>> Hi Taher
>>
>> Great work! I tried it out and found it simple and easy to use (and
>> write!). When can we start writing ? :-)
>>
>> I was thinking to start with basic descriptions of each of the
>> applications, then see how it evolves from there. We can maybe recover some
>> documentation content from various sources including our existing online
>> help system and the wiki.
>>
>> The documentation structure will maybe need some thought, and we may need
>> to sort out some common template or guidelines around it.
>>
>> Thanks
>> Sharan
>>
>> On 2018-01-14 12:33, "Sharan Foga"<[hidden email]> wrote:
>>>
>>> Excellent news Taher!
>>>
>>> Thanks very much for your effort on this. I'll aim to try it out this
>>> week and come back with any feedback.
>>>
>>> Thanks
>>> Sharan
>>>
>>> On 2018-01-12 17:36, Taher Alkhateeb <[hidden email]> wrote:
>>>>
>>>> Hello everyone,
>>>>
>>>> Sorry for the delay on my part, I got a little preoccupied. Anyway, I
>>>> have a small patch in [1] that provides the PoC for integrating
>>>> asciidoctor with OFBiz. I also provided in the the JIRA [1]
>>>> instructions on how to run it. Essentially, this allows you to create
>>>> documentation for any component by simply creating a src/docs/asciidoc
>>>> directory and putting files inside.
>>>>
>>>> This solution is flexible and allows us to build bigger designs on top
>>>> of it. Please review it and tell me if you like the general design.
>>>>
>>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>>>>
>>>> On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
>>>> <[hidden email]> wrote:
>>>>>
>>>>> Hello Folks,
>>>>>
>>>>> We've had this discussion multiple times in the past, but I think I
>>>>> have a more concrete idea this time for solving this problem. In the
>>>>> past few weeks we've been working internally in Pythys to figure out
>>>>> the best way to write and distribute documentation, and I think most
>>>>> of that is applicable to OFBiz.
>>>>>
>>>>> In a nutshell, here is the idea (practically) for how to proceed:
>>>>>
>>>>> - The documentation language to use is Asciidoc
>>>>> - The documentation tool is Asciidoctor
>>>>> - Publishing happens through Gradle using the asciidoctor gradle
>>>>> plugin (not the OFBiz framework or anything else).
>>>>> - The only place where we write documentation is inside the code base
>>>>> - Every component contains its own documentation
>>>>> - General documentation goes to either a standalone directory or a
>>>>> generic component like common or base
>>>>> - As much as possible, documentation files are small and focused on
>>>>> one topic. And then other longer documents are constructed from these
>>>>> snippets of documentation.
>>>>> - We publish to all formats including PDF for users, or HTML for
>>>>> embedded help and wiki pages. So OFBiz does not parse docbook for its
>>>>> help system, instead it just renders generated HTML.
>>>>>
>>>>> As I've worked extensively with Asciidoc I find it easy to pickup
>>>>> (like markdown) but also modular (like docbook and dita). It's also
>>>>> neat that you can sprinkle variables all around in your document so
>>>>> that update is no longer a painful grepping process.
>>>>>
>>>>> Would love to hear your thoughts on this.
>>>>>
>>>>> Cheers,
>>>>>
>>>>> Taher Alkhateeb
>
>

[Craig Parker]

And I'm just realizing... You're not talking end user docs are you?


On 01/17/2018 10:54 AM, Taher Alkhateeb wrote:

> So I have thought of a few ways to implement our documentation
> structure and I would like to share my ideas with everyone to see what
> you prefer to go with. Here goes:
>
> - First, let's categorize documentation as:
>    - component-specific
>    - general documentation
> - component specific documentation lives inside the component in
> "/src/docs/asciidoc". It is a self contained piece of documentation.
> - Every component has only _one_ publishable document. There is a
> methodology in asciidoctor to denote public and private documents.
> private documents will not be published but only included in other
> documents. This way we can make a modular documentation for each
> component while publishing only one output.
> - general documentation (i'm still scratching my head over this one)
> could be placed maybe in framework/base. What it does is explain high
> level information about the framework and explain general conceptual
> principles of how things work.
> - We can combine the entire documentation of everything (framework +
> applications) in a single document that references all the other
> documents and maybe we can place it at the top-level directory and
> call it something like ofbiz-documentation.adoc
> - Plugins are not included in the full documentation, they are self
> contained and are not part of the _big_ published manual. instead each
> plugin has its own mini manual.
> - We declare three gradle tasks similar to the below:
>    - "./gradlew publishComponentDocs": publish documentation for a
> specific component / plugin which requires a componentName flag.
>    - "./gradlew publishAllComponentsDocs": publish documentation for
> all components / plugins
>    - "./gradlew publishOfbizDocs": publish the master documentation
> manual that combines everything.
>
> This is a brain dump so I leave it to you fine folks to refine the
> ideas and decide where we should go.
>
> Cheers,
>
> Taher Alkhateeb
>
> On Wed, Jan 17, 2018 at 6:08 PM, Craig Parker <[hidden email]> wrote:
>> I think the doc structure ought to mirror the menu in the software, or are
>> you talking about how a doc itself is laid out?
>>
>>
>>
>> On 01/17/2018 09:25 AM, Sharan Foga wrote:
>>> Hi Taher
>>>
>>> Great work! I tried it out and found it simple and easy to use (and
>>> write!). When can we start writing ? :-)
>>>
>>> I was thinking to start with basic descriptions of each of the
>>> applications, then see how it evolves from there. We can maybe recover some
>>> documentation content from various sources including our existing online
>>> help system and the wiki.
>>>
>>> The documentation structure will maybe need some thought, and we may need
>>> to sort out some common template or guidelines around it.
>>>
>>> Thanks
>>> Sharan
>>>
>>> On 2018-01-14 12:33, "Sharan Foga"<[hidden email]> wrote:
>>>> Excellent news Taher!
>>>>
>>>> Thanks very much for your effort on this. I'll aim to try it out this
>>>> week and come back with any feedback.
>>>>
>>>> Thanks
>>>> Sharan
>>>>
>>>> On 2018-01-12 17:36, Taher Alkhateeb <[hidden email]> wrote:
>>>>> Hello everyone,
>>>>>
>>>>> Sorry for the delay on my part, I got a little preoccupied. Anyway, I
>>>>> have a small patch in [1] that provides the PoC for integrating
>>>>> asciidoctor with OFBiz. I also provided in the the JIRA [1]
>>>>> instructions on how to run it. Essentially, this allows you to create
>>>>> documentation for any component by simply creating a src/docs/asciidoc
>>>>> directory and putting files inside.
>>>>>
>>>>> This solution is flexible and allows us to build bigger designs on top
>>>>> of it. Please review it and tell me if you like the general design.
>>>>>
>>>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>>>>>
>>>>> On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
>>>>> <[hidden email]> wrote:
>>>>>> Hello Folks,
>>>>>>
>>>>>> We've had this discussion multiple times in the past, but I think I
>>>>>> have a more concrete idea this time for solving this problem. In the
>>>>>> past few weeks we've been working internally in Pythys to figure out
>>>>>> the best way to write and distribute documentation, and I think most
>>>>>> of that is applicable to OFBiz.
>>>>>>
>>>>>> In a nutshell, here is the idea (practically) for how to proceed:
>>>>>>
>>>>>> - The documentation language to use is Asciidoc
>>>>>> - The documentation tool is Asciidoctor
>>>>>> - Publishing happens through Gradle using the asciidoctor gradle
>>>>>> plugin (not the OFBiz framework or anything else).
>>>>>> - The only place where we write documentation is inside the code base
>>>>>> - Every component contains its own documentation
>>>>>> - General documentation goes to either a standalone directory or a
>>>>>> generic component like common or base
>>>>>> - As much as possible, documentation files are small and focused on
>>>>>> one topic. And then other longer documents are constructed from these
>>>>>> snippets of documentation.
>>>>>> - We publish to all formats including PDF for users, or HTML for
>>>>>> embedded help and wiki pages. So OFBiz does not parse docbook for its
>>>>>> help system, instead it just renders generated HTML.
>>>>>>
>>>>>> As I've worked extensively with Asciidoc I find it easy to pickup
>>>>>> (like markdown) but also modular (like docbook and dita). It's also
>>>>>> neat that you can sprinkle variables all around in your document so
>>>>>> that update is no longer a painful grepping process.
>>>>>>
>>>>>> Would love to hear your thoughts on this.
>>>>>>
>>>>>> Cheers,
>>>>>>
>>>>>> Taher Alkhateeb
>>

[taher]

Also thinking about it just after clicking send, maybe there is no
need for the publishComponentDocs and publishAllComponentsDocs tasks
because we should treat all OFBiz documentation as one piece. and
Instead we can have a ./gradlew publishPluginDocs. So throwing another
idea in the pile

On Wed, Jan 17, 2018 at 6:54 PM, Taher Alkhateeb
<[hidden email]> wrote:

> So I have thought of a few ways to implement our documentation
> structure and I would like to share my ideas with everyone to see what
> you prefer to go with. Here goes:
>
> - First, let's categorize documentation as:
>   - component-specific
>   - general documentation
> - component specific documentation lives inside the component in
> "/src/docs/asciidoc". It is a self contained piece of documentation.
> - Every component has only _one_ publishable document. There is a
> methodology in asciidoctor to denote public and private documents.
> private documents will not be published but only included in other
> documents. This way we can make a modular documentation for each
> component while publishing only one output.
> - general documentation (i'm still scratching my head over this one)
> could be placed maybe in framework/base. What it does is explain high
> level information about the framework and explain general conceptual
> principles of how things work.
> - We can combine the entire documentation of everything (framework +
> applications) in a single document that references all the other
> documents and maybe we can place it at the top-level directory and
> call it something like ofbiz-documentation.adoc
> - Plugins are not included in the full documentation, they are self
> contained and are not part of the _big_ published manual. instead each
> plugin has its own mini manual.
> - We declare three gradle tasks similar to the below:
>   - "./gradlew publishComponentDocs": publish documentation for a
> specific component / plugin which requires a componentName flag.
>   - "./gradlew publishAllComponentsDocs": publish documentation for
> all components / plugins
>   - "./gradlew publishOfbizDocs": publish the master documentation
> manual that combines everything.
>
> This is a brain dump so I leave it to you fine folks to refine the
> ideas and decide where we should go.
>
> Cheers,
>
> Taher Alkhateeb
>
> On Wed, Jan 17, 2018 at 6:08 PM, Craig Parker <[hidden email]> wrote:
>> I think the doc structure ought to mirror the menu in the software, or are
>> you talking about how a doc itself is laid out?
>>
>>
>>
>> On 01/17/2018 09:25 AM, Sharan Foga wrote:
>>>
>>> Hi Taher
>>>
>>> Great work! I tried it out and found it simple and easy to use (and
>>> write!). When can we start writing ? :-)
>>>
>>> I was thinking to start with basic descriptions of each of the
>>> applications, then see how it evolves from there. We can maybe recover some
>>> documentation content from various sources including our existing online
>>> help system and the wiki.
>>>
>>> The documentation structure will maybe need some thought, and we may need
>>> to sort out some common template or guidelines around it.
>>>
>>> Thanks
>>> Sharan
>>>
>>> On 2018-01-14 12:33, "Sharan Foga"<[hidden email]> wrote:
>>>>
>>>> Excellent news Taher!
>>>>
>>>> Thanks very much for your effort on this. I'll aim to try it out this
>>>> week and come back with any feedback.
>>>>
>>>> Thanks
>>>> Sharan
>>>>
>>>> On 2018-01-12 17:36, Taher Alkhateeb <[hidden email]> wrote:
>>>>>
>>>>> Hello everyone,
>>>>>
>>>>> Sorry for the delay on my part, I got a little preoccupied. Anyway, I
>>>>> have a small patch in [1] that provides the PoC for integrating
>>>>> asciidoctor with OFBiz. I also provided in the the JIRA [1]
>>>>> instructions on how to run it. Essentially, this allows you to create
>>>>> documentation for any component by simply creating a src/docs/asciidoc
>>>>> directory and putting files inside.
>>>>>
>>>>> This solution is flexible and allows us to build bigger designs on top
>>>>> of it. Please review it and tell me if you like the general design.
>>>>>
>>>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>>>>>
>>>>> On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
>>>>> <[hidden email]> wrote:
>>>>>>
>>>>>> Hello Folks,
>>>>>>
>>>>>> We've had this discussion multiple times in the past, but I think I
>>>>>> have a more concrete idea this time for solving this problem. In the
>>>>>> past few weeks we've been working internally in Pythys to figure out
>>>>>> the best way to write and distribute documentation, and I think most
>>>>>> of that is applicable to OFBiz.
>>>>>>
>>>>>> In a nutshell, here is the idea (practically) for how to proceed:
>>>>>>
>>>>>> - The documentation language to use is Asciidoc
>>>>>> - The documentation tool is Asciidoctor
>>>>>> - Publishing happens through Gradle using the asciidoctor gradle
>>>>>> plugin (not the OFBiz framework or anything else).
>>>>>> - The only place where we write documentation is inside the code base
>>>>>> - Every component contains its own documentation
>>>>>> - General documentation goes to either a standalone directory or a
>>>>>> generic component like common or base
>>>>>> - As much as possible, documentation files are small and focused on
>>>>>> one topic. And then other longer documents are constructed from these
>>>>>> snippets of documentation.
>>>>>> - We publish to all formats including PDF for users, or HTML for
>>>>>> embedded help and wiki pages. So OFBiz does not parse docbook for its
>>>>>> help system, instead it just renders generated HTML.
>>>>>>
>>>>>> As I've worked extensively with Asciidoc I find it easy to pickup
>>>>>> (like markdown) but also modular (like docbook and dita). It's also
>>>>>> neat that you can sprinkle variables all around in your document so
>>>>>> that update is no longer a painful grepping process.
>>>>>>
>>>>>> Would love to hear your thoughts on this.
>>>>>>
>>>>>> Cheers,
>>>>>>
>>>>>> Taher Alkhateeb
>>
>>

[taher]

I'm not sure, but I think we should document "everything" like user,
developer, etc. It's up to all of us to decide and I have no strong
opinion on this.

On Wed, Jan 17, 2018 at 6:56 PM, Craig Parker <[hidden email]> wrote:

> And I'm just realizing... You're not talking end user docs are you?
>
>
>
> On 01/17/2018 10:54 AM, Taher Alkhateeb wrote:
>>
>> So I have thought of a few ways to implement our documentation
>> structure and I would like to share my ideas with everyone to see what
>> you prefer to go with. Here goes:
>>
>> - First, let's categorize documentation as:
>>    - component-specific
>>    - general documentation
>> - component specific documentation lives inside the component in
>> "/src/docs/asciidoc". It is a self contained piece of documentation.
>> - Every component has only _one_ publishable document. There is a
>> methodology in asciidoctor to denote public and private documents.
>> private documents will not be published but only included in other
>> documents. This way we can make a modular documentation for each
>> component while publishing only one output.
>> - general documentation (i'm still scratching my head over this one)
>> could be placed maybe in framework/base. What it does is explain high
>> level information about the framework and explain general conceptual
>> principles of how things work.
>> - We can combine the entire documentation of everything (framework +
>> applications) in a single document that references all the other
>> documents and maybe we can place it at the top-level directory and
>> call it something like ofbiz-documentation.adoc
>> - Plugins are not included in the full documentation, they are self
>> contained and are not part of the _big_ published manual. instead each
>> plugin has its own mini manual.
>> - We declare three gradle tasks similar to the below:
>>    - "./gradlew publishComponentDocs": publish documentation for a
>> specific component / plugin which requires a componentName flag.
>>    - "./gradlew publishAllComponentsDocs": publish documentation for
>> all components / plugins
>>    - "./gradlew publishOfbizDocs": publish the master documentation
>> manual that combines everything.
>>
>> This is a brain dump so I leave it to you fine folks to refine the
>> ideas and decide where we should go.
>>
>> Cheers,
>>
>> Taher Alkhateeb
>>
>> On Wed, Jan 17, 2018 at 6:08 PM, Craig Parker <[hidden email]> wrote:
>>>
>>> I think the doc structure ought to mirror the menu in the software, or
>>> are
>>> you talking about how a doc itself is laid out?
>>>
>>>
>>>
>>> On 01/17/2018 09:25 AM, Sharan Foga wrote:
>>>>
>>>> Hi Taher
>>>>
>>>> Great work! I tried it out and found it simple and easy to use (and
>>>> write!). When can we start writing ? :-)
>>>>
>>>> I was thinking to start with basic descriptions of each of the
>>>> applications, then see how it evolves from there. We can maybe recover
>>>> some
>>>> documentation content from various sources including our existing online
>>>> help system and the wiki.
>>>>
>>>> The documentation structure will maybe need some thought, and we may
>>>> need
>>>> to sort out some common template or guidelines around it.
>>>>
>>>> Thanks
>>>> Sharan
>>>>
>>>> On 2018-01-14 12:33, "Sharan Foga"<[hidden email]> wrote:
>>>>>
>>>>> Excellent news Taher!
>>>>>
>>>>> Thanks very much for your effort on this. I'll aim to try it out this
>>>>> week and come back with any feedback.
>>>>>
>>>>> Thanks
>>>>> Sharan
>>>>>
>>>>> On 2018-01-12 17:36, Taher Alkhateeb <[hidden email]>
>>>>> wrote:
>>>>>>
>>>>>> Hello everyone,
>>>>>>
>>>>>> Sorry for the delay on my part, I got a little preoccupied. Anyway, I
>>>>>> have a small patch in [1] that provides the PoC for integrating
>>>>>> asciidoctor with OFBiz. I also provided in the the JIRA [1]
>>>>>> instructions on how to run it. Essentially, this allows you to create
>>>>>> documentation for any component by simply creating a src/docs/asciidoc
>>>>>> directory and putting files inside.
>>>>>>
>>>>>> This solution is flexible and allows us to build bigger designs on top
>>>>>> of it. Please review it and tell me if you like the general design.
>>>>>>
>>>>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>>>>>>
>>>>>> On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
>>>>>> <[hidden email]> wrote:
>>>>>>>
>>>>>>> Hello Folks,
>>>>>>>
>>>>>>> We've had this discussion multiple times in the past, but I think I
>>>>>>> have a more concrete idea this time for solving this problem. In the
>>>>>>> past few weeks we've been working internally in Pythys to figure out
>>>>>>> the best way to write and distribute documentation, and I think most
>>>>>>> of that is applicable to OFBiz.
>>>>>>>
>>>>>>> In a nutshell, here is the idea (practically) for how to proceed:
>>>>>>>
>>>>>>> - The documentation language to use is Asciidoc
>>>>>>> - The documentation tool is Asciidoctor
>>>>>>> - Publishing happens through Gradle using the asciidoctor gradle
>>>>>>> plugin (not the OFBiz framework or anything else).
>>>>>>> - The only place where we write documentation is inside the code base
>>>>>>> - Every component contains its own documentation
>>>>>>> - General documentation goes to either a standalone directory or a
>>>>>>> generic component like common or base
>>>>>>> - As much as possible, documentation files are small and focused on
>>>>>>> one topic. And then other longer documents are constructed from these
>>>>>>> snippets of documentation.
>>>>>>> - We publish to all formats including PDF for users, or HTML for
>>>>>>> embedded help and wiki pages. So OFBiz does not parse docbook for its
>>>>>>> help system, instead it just renders generated HTML.
>>>>>>>
>>>>>>> As I've worked extensively with Asciidoc I find it easy to pickup
>>>>>>> (like markdown) but also modular (like docbook and dita). It's also
>>>>>>> neat that you can sprinkle variables all around in your document so
>>>>>>> that update is no longer a painful grepping process.
>>>>>>>
>>>>>>> Would love to hear your thoughts on this.
>>>>>>>
>>>>>>> Cheers,
>>>>>>>
>>>>>>> Taher Alkhateeb
>>>
>>>
>

[Sharan Foga]

Hi Craig

Generally I was thinking about how it was going to be laid out. So if you think about one big consolidated OFBiz Guide that contains both technical and user guide info, then what would that look like? How would you structure the one consolidated output?

I don't think that it would necessarily need to mirror the exact structure of the menus - it just depends on how it's linked to the overall process (if you are thinking user docs). Also some of the things we need to write about won't appear anywhere in the menus - so we'll need a general place for that.

My comment was also about the format of each of the source documents to ensure consistency. Since we are going to be consolidating many smaller documents into one big one, so it needs to look like they belong together.

Hope that makes it clearer.

Thanks
Sharan

On 2018-01-17 16:08, Craig Parker <[hidden email]> wrote:

> I think the doc structure ought to mirror the menu in the software, or
> are you talking about how a doc itself is laid out?
>
>
> On 01/17/2018 09:25 AM, Sharan Foga wrote:
> > Hi Taher
> >
> > Great work! I tried it out and found it simple and easy to use (and write!). When can we start writing ? :-)
> >
> > I was thinking to start with basic descriptions of each of the applications, then see how it evolves from there. We can maybe recover some documentation content from various sources including our existing online help system and the wiki.
> >
> > The documentation structure will maybe need some thought, and we may need to sort out some common template or guidelines around it.
> >
> > Thanks
> > Sharan
> >
> > On 2018-01-14 12:33, "Sharan Foga"<[hidden email]> wrote:
> >> Excellent news Taher!
> >>
> >> Thanks very much for your effort on this. I'll aim to try it out this week and come back with any feedback.
> >>
> >> Thanks
> >> Sharan
> >>
> >> On 2018-01-12 17:36, Taher Alkhateeb <[hidden email]> wrote:
> >>> Hello everyone,
> >>>
> >>> Sorry for the delay on my part, I got a little preoccupied. Anyway, I
> >>> have a small patch in [1] that provides the PoC for integrating
> >>> asciidoctor with OFBiz. I also provided in the the JIRA [1]
> >>> instructions on how to run it. Essentially, this allows you to create
> >>> documentation for any component by simply creating a src/docs/asciidoc
> >>> directory and putting files inside.
> >>>
> >>> This solution is flexible and allows us to build bigger designs on top
> >>> of it. Please review it and tell me if you like the general design.
> >>>
> >>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
> >>>
> >>> On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
> >>> <[hidden email]> wrote:
> >>>> Hello Folks,
> >>>>
> >>>> We've had this discussion multiple times in the past, but I think I
> >>>> have a more concrete idea this time for solving this problem. In the
> >>>> past few weeks we've been working internally in Pythys to figure out
> >>>> the best way to write and distribute documentation, and I think most
> >>>> of that is applicable to OFBiz.
> >>>>
> >>>> In a nutshell, here is the idea (practically) for how to proceed:
> >>>>
> >>>> - The documentation language to use is Asciidoc
> >>>> - The documentation tool is Asciidoctor
> >>>> - Publishing happens through Gradle using the asciidoctor gradle
> >>>> plugin (not the OFBiz framework or anything else).
> >>>> - The only place where we write documentation is inside the code base
> >>>> - Every component contains its own documentation
> >>>> - General documentation goes to either a standalone directory or a
> >>>> generic component like common or base
> >>>> - As much as possible, documentation files are small and focused on
> >>>> one topic. And then other longer documents are constructed from these
> >>>> snippets of documentation.
> >>>> - We publish to all formats including PDF for users, or HTML for
> >>>> embedded help and wiki pages. So OFBiz does not parse docbook for its
> >>>> help system, instead it just renders generated HTML.
> >>>>
> >>>> As I've worked extensively with Asciidoc I find it easy to pickup
> >>>> (like markdown) but also modular (like docbook and dita). It's also
> >>>> neat that you can sprinkle variables all around in your document so
> >>>> that update is no longer a painful grepping process.
> >>>>
> >>>> Would love to hear your thoughts on this.
> >>>>
> >>>> Cheers,
> >>>>
> >>>> Taher Alkhateeb
>
>

[Sharan Foga]

Hi Taher

I've included some comments inline.

On 2018-01-17 16:54, Taher Alkhateeb <[hidden email]> wrote:
> So I have thought of a few ways to implement our documentation
> structure and I would like to share my ideas with everyone to see what
> you prefer to go with. Here goes:
>
> - First, let's categorize documentation as:
>   - component-specific
>   - general documentation

I like this as it is a simple and easy way for us to do our first split. In the past we have tried to put everything together in a way that doesn't really fit, so doing an initial is it this or that, makes it a lot easier.

> - component specific documentation lives inside the component in
> "/src/docs/asciidoc". It is a self contained piece of documentation.
> - Every component has only _one_ publishable document. There is a
> methodology in asciidoctor to denote public and private documents.
> private documents will not be published but only included in other
> documents. This way we can make a modular documentation for each
> component while publishing only one output.

I like the idea of only one publishable document per component. That means that we have a fixed scope for what the documentation needs to cover (so no documentation creep). I'm sure we will get interlinking between components so can plan for it and link when ready.


> - general documentation (i'm still scratching my head over this one)
> could be placed maybe in framework/base. What it does is explain high
> level information about the framework and explain general conceptual
> principles of how things work.
> - We can combine the entire documentation of everything (framework +
> applications) in a single document that references all the other
> documents and maybe we can place it at the top-level directory and
> call it something like ofbiz-documentation.adoc

As long as people can easily navigate it and find what they want quickly then one document could be the solution. At least we can start with that and if does start to become too heavy then look at re-arranging it or splitting it up.

In the past I think all the details from the online help were published as a consolidated html file via the OFBiz cms. I think it was too linked to the individual screens so as standalone document without the screens, it wasn't as useful as it could be.


> - Plugins are not included in the full documentation, they are self
> contained and are not part of the _big_ published manual. instead each
> plugin has its own mini manual.

+1 on this. We will have to maintain the official plugin documentation, and I would see that people writing their own plugins can use this same mechanism to include their specific documentation.


> - We declare three gradle tasks similar to the below:
>   - "./gradlew publishComponentDocs": publish documentation for a
> specific component / plugin which requires a componentName flag.
>   - "./gradlew publishAllComponentsDocs": publish documentation for
> all components / plugins
>   - "./gradlew publishOfbizDocs": publish the master documentation
> manual that combines everything.
>

As per your later response, I think we could reduce the gradle tasks to one for the framework+core application docs and one for the plugins.

Thanks for sharing - you have some good ideas here.  Let's keep the discussion going :-) so anyone with other ideas, comments and feedback, please feel free to join the conversation.

Thanks
Sharan

> This is a brain dump so I leave it to you fine folks to refine the
> ideas and decide where we should go.
>
> Cheers,
>
> Taher Alkhateeb
>
> On Wed, Jan 17, 2018 at 6:08 PM, Craig Parker <[hidden email]> wrote:
> > I think the doc structure ought to mirror the menu in the software, or are
> > you talking about how a doc itself is laid out?
> >
> >
> >
> > On 01/17/2018 09:25 AM, Sharan Foga wrote:
> >>
> >> Hi Taher
> >>
> >> Great work! I tried it out and found it simple and easy to use (and
> >> write!). When can we start writing ? :-)
> >>
> >> I was thinking to start with basic descriptions of each of the
> >> applications, then see how it evolves from there. We can maybe recover some
> >> documentation content from various sources including our existing online
> >> help system and the wiki.
> >>
> >> The documentation structure will maybe need some thought, and we may need
> >> to sort out some common template or guidelines around it.
> >>
> >> Thanks
> >> Sharan
> >>
> >> On 2018-01-14 12:33, "Sharan Foga"<[hidden email]> wrote:
> >>>
> >>> Excellent news Taher!
> >>>
> >>> Thanks very much for your effort on this. I'll aim to try it out this
> >>> week and come back with any feedback.
> >>>
> >>> Thanks
> >>> Sharan
> >>>
> >>> On 2018-01-12 17:36, Taher Alkhateeb <[hidden email]> wrote:
> >>>>
> >>>> Hello everyone,
> >>>>
> >>>> Sorry for the delay on my part, I got a little preoccupied. Anyway, I
> >>>> have a small patch in [1] that provides the PoC for integrating
> >>>> asciidoctor with OFBiz. I also provided in the the JIRA [1]
> >>>> instructions on how to run it. Essentially, this allows you to create
> >>>> documentation for any component by simply creating a src/docs/asciidoc
> >>>> directory and putting files inside.
> >>>>
> >>>> This solution is flexible and allows us to build bigger designs on top
> >>>> of it. Please review it and tell me if you like the general design.
> >>>>
> >>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
> >>>>
> >>>> On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
> >>>> <[hidden email]> wrote:
> >>>>>
> >>>>> Hello Folks,
> >>>>>
> >>>>> We've had this discussion multiple times in the past, but I think I
> >>>>> have a more concrete idea this time for solving this problem. In the
> >>>>> past few weeks we've been working internally in Pythys to figure out
> >>>>> the best way to write and distribute documentation, and I think most
> >>>>> of that is applicable to OFBiz.
> >>>>>
> >>>>> In a nutshell, here is the idea (practically) for how to proceed:
> >>>>>
> >>>>> - The documentation language to use is Asciidoc
> >>>>> - The documentation tool is Asciidoctor
> >>>>> - Publishing happens through Gradle using the asciidoctor gradle
> >>>>> plugin (not the OFBiz framework or anything else).
> >>>>> - The only place where we write documentation is inside the code base
> >>>>> - Every component contains its own documentation
> >>>>> - General documentation goes to either a standalone directory or a
> >>>>> generic component like common or base
> >>>>> - As much as possible, documentation files are small and focused on
> >>>>> one topic. And then other longer documents are constructed from these
> >>>>> snippets of documentation.
> >>>>> - We publish to all formats including PDF for users, or HTML for
> >>>>> embedded help and wiki pages. So OFBiz does not parse docbook for its
> >>>>> help system, instead it just renders generated HTML.
> >>>>>
> >>>>> As I've worked extensively with Asciidoc I find it easy to pickup
> >>>>> (like markdown) but also modular (like docbook and dita). It's also
> >>>>> neat that you can sprinkle variables all around in your document so
> >>>>> that update is no longer a painful grepping process.
> >>>>>
> >>>>> Would love to hear your thoughts on this.
> >>>>>
> >>>>> Cheers,
> >>>>>
> >>>>> Taher Alkhateeb
> >
> >
>

[Jacques Le Roux]

Inline...


Le 18/01/2018 à 13:54, Sharan Foga a écrit :

> Hi Taher
>
> I've included some comments inline.
>
> On 2018-01-17 16:54, Taher Alkhateeb <[hidden email]> wrote:
>> So I have thought of a few ways to implement our documentation
>> structure and I would like to share my ideas with everyone to see what
>> you prefer to go with. Here goes:
>>
>> - First, let's categorize documentation as:
>>    - component-specific
>>    - general documentation
> I like this as it is a simple and easy way for us to do our first split. In the past we have tried to put everything together in a way that doesn't really fit, so doing an initial is it this or that, makes it a lot easier.

+1

>> - component specific documentation lives inside the component in
>> "/src/docs/asciidoc". It is a self contained piece of documentation.
>> - Every component has only _one_ publishable document. There is a
>> methodology in asciidoctor to denote public and private documents.
>> private documents will not be published but only included in other
>> documents. This way we can make a modular documentation for each
>> component while publishing only one output.
> I like the idea of only one publishable document per component. That means that we have a fixed scope for what the documentation needs to cover (so no documentation creep). I'm sure we will get interlinking between components so can plan for it and link when ready.
+1 and +1 for inter-links idea

>> - general documentation (i'm still scratching my head over this one)
>> could be placed maybe in framework/base. What it does is explain high
>> level information about the framework and explain general conceptual
>> principles of how things work.
I'm not sure this can be called general documentation. I was thinking at another place initially, one place where people should look intuitively, like
a documentation sub-dir of root. But we need to define what we call general documentation.

>> - We can combine the entire documentation of everything (framework +
>> applications) in a single document that references all the other
>> documents and maybe we can place it at the top-level directory and
>> call it something like ofbiz-documentation.adoc
> As long as people can easily navigate it and find what they want quickly then one document could be the solution. At least we can start with that and if does start to become too heavy then look at re-arranging it or splitting it up.
That sounds like a good idea, finding an ofbiz-documentation.adoc file is as easy as finding a documentation sub-dir of root. But then we need to
remember that it's not often the content that confuse people but how to access it. So we need to think about the structure of this document (like
separating end users and technical doc at the 1st level. Maybe we can think about having end users and technical doc separated in component?

> In the past I think all the details from the online help were published as a consolidated html file via the OFBiz cms. I think it was too linked to the individual screens so as standalone document without the screens, it wasn't as useful as it could be.
I think people were also not much aware of this document, so it got not much critics and was not improved

> - Plugins are not included in the full documentation, they are self
> contained and are not part of the _big_ published manual. instead each
> plugin has its own mini manual.
> +1 on this. We will have to maintain the official plugin documentation, and I would see that people writing their own plugins can use this same mechanism to include their specific documentation.
Sure +1!

>
>
>> - We declare three gradle tasks similar to the below:
>>    - "./gradlew publishComponentDocs": publish documentation for a
>> specific component / plugin which requires a componentName flag.
>>    - "./gradlew publishAllComponentsDocs": publish documentation for
>> all components / plugins
>>    - "./gradlew publishOfbizDocs": publish the master documentation
>> manual that combines everything.
>>
> As per your later response, I think we could reduce the gradle tasks to one for the framework+core application docs and one for the plugins.
>
> Thanks for sharing - you have some good ideas here.  Let's keep the discussion going :-) so anyone with other ideas, comments and feedback, please feel free to join the conversation.

I agree, let's continue to share :)

Jacques

>
> Thanks
> Sharan
>
>
>> This is a brain dump so I leave it to you fine folks to refine the
>> ideas and decide where we should go.
>>
>> Cheers,
>>
>> Taher Alkhateeb
>>
>> On Wed, Jan 17, 2018 at 6:08 PM, Craig Parker <[hidden email]> wrote:
>>> I think the doc structure ought to mirror the menu in the software, or are
>>> you talking about how a doc itself is laid out?
>>>
>>>
>>>
>>> On 01/17/2018 09:25 AM, Sharan Foga wrote:
>>>> Hi Taher
>>>>
>>>> Great work! I tried it out and found it simple and easy to use (and
>>>> write!). When can we start writing ? :-)
>>>>
>>>> I was thinking to start with basic descriptions of each of the
>>>> applications, then see how it evolves from there. We can maybe recover some
>>>> documentation content from various sources including our existing online
>>>> help system and the wiki.
>>>>
>>>> The documentation structure will maybe need some thought, and we may need
>>>> to sort out some common template or guidelines around it.
>>>>
>>>> Thanks
>>>> Sharan
>>>>
>>>> On 2018-01-14 12:33, "Sharan Foga"<[hidden email]> wrote:
>>>>> Excellent news Taher!
>>>>>
>>>>> Thanks very much for your effort on this. I'll aim to try it out this
>>>>> week and come back with any feedback.
>>>>>
>>>>> Thanks
>>>>> Sharan
>>>>>
>>>>> On 2018-01-12 17:36, Taher Alkhateeb <[hidden email]> wrote:
>>>>>> Hello everyone,
>>>>>>
>>>>>> Sorry for the delay on my part, I got a little preoccupied. Anyway, I
>>>>>> have a small patch in [1] that provides the PoC for integrating
>>>>>> asciidoctor with OFBiz. I also provided in the the JIRA [1]
>>>>>> instructions on how to run it. Essentially, this allows you to create
>>>>>> documentation for any component by simply creating a src/docs/asciidoc
>>>>>> directory and putting files inside.
>>>>>>
>>>>>> This solution is flexible and allows us to build bigger designs on top
>>>>>> of it. Please review it and tell me if you like the general design.
>>>>>>
>>>>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>>>>>>
>>>>>> On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
>>>>>> <[hidden email]> wrote:
>>>>>>> Hello Folks,
>>>>>>>
>>>>>>> We've had this discussion multiple times in the past, but I think I
>>>>>>> have a more concrete idea this time for solving this problem. In the
>>>>>>> past few weeks we've been working internally in Pythys to figure out
>>>>>>> the best way to write and distribute documentation, and I think most
>>>>>>> of that is applicable to OFBiz.
>>>>>>>
>>>>>>> In a nutshell, here is the idea (practically) for how to proceed:
>>>>>>>
>>>>>>> - The documentation language to use is Asciidoc
>>>>>>> - The documentation tool is Asciidoctor
>>>>>>> - Publishing happens through Gradle using the asciidoctor gradle
>>>>>>> plugin (not the OFBiz framework or anything else).
>>>>>>> - The only place where we write documentation is inside the code base
>>>>>>> - Every component contains its own documentation
>>>>>>> - General documentation goes to either a standalone directory or a
>>>>>>> generic component like common or base
>>>>>>> - As much as possible, documentation files are small and focused on
>>>>>>> one topic. And then other longer documents are constructed from these
>>>>>>> snippets of documentation.
>>>>>>> - We publish to all formats including PDF for users, or HTML for
>>>>>>> embedded help and wiki pages. So OFBiz does not parse docbook for its
>>>>>>> help system, instead it just renders generated HTML.
>>>>>>>
>>>>>>> As I've worked extensively with Asciidoc I find it easy to pickup
>>>>>>> (like markdown) but also modular (like docbook and dita). It's also
>>>>>>> neat that you can sprinkle variables all around in your document so
>>>>>>> that update is no longer a painful grepping process.
>>>>>>>
>>>>>>> Would love to hear your thoughts on this.
>>>>>>>
>>>>>>> Cheers,
>>>>>>>
>>>>>>> Taher Alkhateeb
>>>

[Jacques Le Roux]

Hi Sharan, Craig,

We already have a document that consolidates many smaller documents into itself, but as said Sharan in another reply it got not much attention because
it was maybe not statisfying (though had interesting info)

https://demo-trunk.ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_HTML

My 2cts

Jacques


Le 18/01/2018 à 13:31, Sharan Foga a écrit :

> Hi Craig
>
> Generally I was thinking about how it was going to be laid out. So if you think about one big consolidated OFBiz Guide that contains both technical and user guide info, then what would that look like? How would you structure the one consolidated output?
>
> I don't think that it would necessarily need to mirror the exact structure of the menus - it just depends on how it's linked to the overall process (if you are thinking user docs). Also some of the things we need to write about won't appear anywhere in the menus - so we'll need a general place for that.
>
> My comment was also about the format of each of the source documents to ensure consistency. Since we are going to be consolidating many smaller documents into one big one, so it needs to look like they belong together.
>
> Hope that makes it clearer.
>
> Thanks
> Sharan
>
> On 2018-01-17 16:08, Craig Parker <[hidden email]> wrote:
>> I think the doc structure ought to mirror the menu in the software, or
>> are you talking about how a doc itself is laid out?
>>
>>
>> On 01/17/2018 09:25 AM, Sharan Foga wrote:
>>> Hi Taher
>>>
>>> Great work! I tried it out and found it simple and easy to use (and write!). When can we start writing ? :-)
>>>
>>> I was thinking to start with basic descriptions of each of the applications, then see how it evolves from there. We can maybe recover some documentation content from various sources including our existing online help system and the wiki.
>>>
>>> The documentation structure will maybe need some thought, and we may need to sort out some common template or guidelines around it.
>>>
>>> Thanks
>>> Sharan
>>>
>>> On 2018-01-14 12:33, "Sharan Foga"<[hidden email]> wrote:
>>>> Excellent news Taher!
>>>>
>>>> Thanks very much for your effort on this. I'll aim to try it out this week and come back with any feedback.
>>>>
>>>> Thanks
>>>> Sharan
>>>>
>>>> On 2018-01-12 17:36, Taher Alkhateeb <[hidden email]> wrote:
>>>>> Hello everyone,
>>>>>
>>>>> Sorry for the delay on my part, I got a little preoccupied. Anyway, I
>>>>> have a small patch in [1] that provides the PoC for integrating
>>>>> asciidoctor with OFBiz. I also provided in the the JIRA [1]
>>>>> instructions on how to run it. Essentially, this allows you to create
>>>>> documentation for any component by simply creating a src/docs/asciidoc
>>>>> directory and putting files inside.
>>>>>
>>>>> This solution is flexible and allows us to build bigger designs on top
>>>>> of it. Please review it and tell me if you like the general design.
>>>>>
>>>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>>>>>
>>>>> On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
>>>>> <[hidden email]> wrote:
>>>>>> Hello Folks,
>>>>>>
>>>>>> We've had this discussion multiple times in the past, but I think I
>>>>>> have a more concrete idea this time for solving this problem. In the
>>>>>> past few weeks we've been working internally in Pythys to figure out
>>>>>> the best way to write and distribute documentation, and I think most
>>>>>> of that is applicable to OFBiz.
>>>>>>
>>>>>> In a nutshell, here is the idea (practically) for how to proceed:
>>>>>>
>>>>>> - The documentation language to use is Asciidoc
>>>>>> - The documentation tool is Asciidoctor
>>>>>> - Publishing happens through Gradle using the asciidoctor gradle
>>>>>> plugin (not the OFBiz framework or anything else).
>>>>>> - The only place where we write documentation is inside the code base
>>>>>> - Every component contains its own documentation
>>>>>> - General documentation goes to either a standalone directory or a
>>>>>> generic component like common or base
>>>>>> - As much as possible, documentation files are small and focused on
>>>>>> one topic. And then other longer documents are constructed from these
>>>>>> snippets of documentation.
>>>>>> - We publish to all formats including PDF for users, or HTML for
>>>>>> embedded help and wiki pages. So OFBiz does not parse docbook for its
>>>>>> help system, instead it just renders generated HTML.
>>>>>>
>>>>>> As I've worked extensively with Asciidoc I find it easy to pickup
>>>>>> (like markdown) but also modular (like docbook and dita). It's also
>>>>>> neat that you can sprinkle variables all around in your document so
>>>>>> that update is no longer a painful grepping process.
>>>>>>
>>>>>> Would love to hear your thoughts on this.
>>>>>>
>>>>>> Cheers,
>>>>>>
>>>>>> Taher Alkhateeb
>>

[taher]

Hi Everyone,

So after a little bit of thinking, I came up with an example file
structure for OFBiz documentation which is listed below. The full
OFBiz manual simply points to all the parts in applications,
framework, and themes to complete the documentation. Any ideas or
feedback is welcomed.

A few points to note:
- Gradle by default ignores any files in the _include sub directory
and so it will only publish the outer document.
- This way, we can publish per component (in isolation) or the whole
documentation by simply publishing the ofbiz-manual.adoc file
- We can further branch out the documentation as needed.

ofbiz
├── applications
│   ├── accounting
│   │   └── src
│   │       └── docs
│   │           └── asciidoc
│   │               ├── accounting.adoc
│   │               └── _include
│   │                   ├── accounting-intro.adoc
│   │                   ├── budgets.adoc
│   │                   ├── invoices.adoc
│   │                   ├── payments.adoc
│   │                   └── understanding-general-ledger.adoc
│   └── humanres
│       └── src
│           └── docs
│               └── asciidoc
│                   ├── humanres.adoc
│                   └── _include
│                       ├── employee-evaluations.adoc
│                       ├── human-resources-intro.adoc
│                       └── punch-in-punch-out.adoc
├── framework
│   ├── base
│   │   └── src
│   │       └── docs
│   │           └── asciidoc
│   │               ├── base.adoc
│   │               └── _include
│   │                   ├── containers.adoc
│   │                   ├── framework-intro.adoc
│   │                   └── loading-components.adoc
│   ├── entity
│   │   └── src
│   │       └── docs
│   │           └── asciidoc
│   │               ├── entity.adoc
│   │               └── _include
│   │                   ├── entity-conditions-api.adoc
│   │                   ├── entity-engine-intro.adoc
│   │                   └── mapping-new-database.adoc
│   └── widget
│       └── src
│           └── docs
│               └── asciidoc
│                   ├── _include
│                   │   ├── form-widgets.adoc
│                   │   ├── screen-widgets.adoc
│                   │   └── widget-system-intro.adoc
│                   └── widget.adoc
├── ofbiz-manual.adoc
├── plugins
│   └── example
│       └── src
│           └── docs
│               └── asciidoc
│                   ├── example.adoc
│                   └── _include
│                       ├── example-intro.adoc
│                       └── extending-example-widgets.adoc
└── themes
    └── common-theme
        └── src
            └── docs
                └── asciidoc
                    ├── common-theme.adoc
                    └── _include
                        ├── ofbiz-themes-intro.adoc
                        ├── web-assets.adoc
                        └── why-common-theme.adoc

On Fri, Jan 19, 2018 at 4:27 PM, Jacques Le Roux
<[hidden email]> wrote:

> Hi Sharan, Craig,
>
> We already have a document that consolidates many smaller documents into
> itself, but as said Sharan in another reply it got not much attention
> because it was maybe not statisfying (though had interesting info)
>
> https://demo-trunk.ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_HTML
>
> My 2cts
>
> Jacques
>
>
>
> Le 18/01/2018 à 13:31, Sharan Foga a écrit :
>>
>> Hi Craig
>>
>> Generally I was thinking about how it was going to be laid out. So if you
>> think about one big consolidated OFBiz Guide that contains both technical
>> and user guide info, then what would that look like? How would you structure
>> the one consolidated output?
>>
>> I don't think that it would necessarily need to mirror the exact structure
>> of the menus - it just depends on how it's linked to the overall process (if
>> you are thinking user docs). Also some of the things we need to write about
>> won't appear anywhere in the menus - so we'll need a general place for that.
>>
>> My comment was also about the format of each of the source documents to
>> ensure consistency. Since we are going to be consolidating many smaller
>> documents into one big one, so it needs to look like they belong together.
>>
>> Hope that makes it clearer.
>>
>> Thanks
>> Sharan
>>
>> On 2018-01-17 16:08, Craig Parker <[hidden email]> wrote:
>>>
>>> I think the doc structure ought to mirror the menu in the software, or
>>> are you talking about how a doc itself is laid out?
>>>
>>>
>>> On 01/17/2018 09:25 AM, Sharan Foga wrote:
>>>>
>>>> Hi Taher
>>>>
>>>> Great work! I tried it out and found it simple and easy to use (and
>>>> write!). When can we start writing ? :-)
>>>>
>>>> I was thinking to start with basic descriptions of each of the
>>>> applications, then see how it evolves from there. We can maybe recover some
>>>> documentation content from various sources including our existing online
>>>> help system and the wiki.
>>>>
>>>> The documentation structure will maybe need some thought, and we may
>>>> need to sort out some common template or guidelines around it.
>>>>
>>>> Thanks
>>>> Sharan
>>>>
>>>> On 2018-01-14 12:33, "Sharan Foga"<[hidden email]> wrote:
>>>>>
>>>>> Excellent news Taher!
>>>>>
>>>>> Thanks very much for your effort on this. I'll aim to try it out this
>>>>> week and come back with any feedback.
>>>>>
>>>>> Thanks
>>>>> Sharan
>>>>>
>>>>> On 2018-01-12 17:36, Taher Alkhateeb <[hidden email]>
>>>>> wrote:
>>>>>>
>>>>>> Hello everyone,
>>>>>>
>>>>>> Sorry for the delay on my part, I got a little preoccupied. Anyway, I
>>>>>> have a small patch in [1] that provides the PoC for integrating
>>>>>> asciidoctor with OFBiz. I also provided in the the JIRA [1]
>>>>>> instructions on how to run it. Essentially, this allows you to create
>>>>>> documentation for any component by simply creating a src/docs/asciidoc
>>>>>> directory and putting files inside.
>>>>>>
>>>>>> This solution is flexible and allows us to build bigger designs on top
>>>>>> of it. Please review it and tell me if you like the general design.
>>>>>>
>>>>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>>>>>>
>>>>>> On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
>>>>>> <[hidden email]> wrote:
>>>>>>>
>>>>>>> Hello Folks,
>>>>>>>
>>>>>>> We've had this discussion multiple times in the past, but I think I
>>>>>>> have a more concrete idea this time for solving this problem. In the
>>>>>>> past few weeks we've been working internally in Pythys to figure out
>>>>>>> the best way to write and distribute documentation, and I think most
>>>>>>> of that is applicable to OFBiz.
>>>>>>>
>>>>>>> In a nutshell, here is the idea (practically) for how to proceed:
>>>>>>>
>>>>>>> - The documentation language to use is Asciidoc
>>>>>>> - The documentation tool is Asciidoctor
>>>>>>> - Publishing happens through Gradle using the asciidoctor gradle
>>>>>>> plugin (not the OFBiz framework or anything else).
>>>>>>> - The only place where we write documentation is inside the code base
>>>>>>> - Every component contains its own documentation
>>>>>>> - General documentation goes to either a standalone directory or a
>>>>>>> generic component like common or base
>>>>>>> - As much as possible, documentation files are small and focused on
>>>>>>> one topic. And then other longer documents are constructed from these
>>>>>>> snippets of documentation.
>>>>>>> - We publish to all formats including PDF for users, or HTML for
>>>>>>> embedded help and wiki pages. So OFBiz does not parse docbook for its
>>>>>>> help system, instead it just renders generated HTML.
>>>>>>>
>>>>>>> As I've worked extensively with Asciidoc I find it easy to pickup
>>>>>>> (like markdown) but also modular (like docbook and dita). It's also
>>>>>>> neat that you can sprinkle variables all around in your document so
>>>>>>> that update is no longer a painful grepping process.
>>>>>>>
>>>>>>> Would love to hear your thoughts on this.
>>>>>>>
>>>>>>> Cheers,
>>>>>>>
>>>>>>> Taher Alkhateeb
>>>
>>>
>

[Sharan Foga]

Hi Taher

The picture helps :-) I had to do a bit of a double-take but I get it now and a big +1

I like what you are suggesting – very nice. It is not entirely following the  menu structure (which is good) instead it is looking at the individual topics. This means that we can make the main document flow a lot easier than simply following what we have in the menus. (e.g We know that you can get to the same place from by different routes on the menus and screens, so focussing on the topic itself will help that.)

I think this will give us the flexibility we need. A standard structure helps people know where to put things.

Thanks
Sharan

On 2018/01/25 11:37:02, Taher Alkhateeb <[hidden email]> wrote:

> Hi Everyone,
>
> So after a little bit of thinking, I came up with an example file
> structure for OFBiz documentation which is listed below. The full
> OFBiz manual simply points to all the parts in applications,
> framework, and themes to complete the documentation. Any ideas or
> feedback is welcomed.
>
> A few points to note:
> - Gradle by default ignores any files in the _include sub directory
> and so it will only publish the outer document.
> - This way, we can publish per component (in isolation) or the whole
> documentation by simply publishing the ofbiz-manual.adoc file
> - We can further branch out the documentation as needed.
>
> ofbiz
> ├── applications
> │   ├── accounting
> │   │   └── src
> │   │       └── docs
> │   │           └── asciidoc
> │   │               ├── accounting.adoc
> │   │               └── _include
> │   │                   ├── accounting-intro.adoc
> │   │                   ├── budgets.adoc
> │   │                   ├── invoices.adoc
> │   │                   ├── payments.adoc
> │   │                   └── understanding-general-ledger.adoc
> │   └── humanres
> │       └── src
> │           └── docs
> │               └── asciidoc
> │                   ├── humanres.adoc
> │                   └── _include
> │                       ├── employee-evaluations.adoc
> │                       ├── human-resources-intro.adoc
> │                       └── punch-in-punch-out.adoc
> ├── framework
> │   ├── base
> │   │   └── src
> │   │       └── docs
> │   │           └── asciidoc
> │   │               ├── base.adoc
> │   │               └── _include
> │   │                   ├── containers.adoc
> │   │                   ├── framework-intro.adoc
> │   │                   └── loading-components.adoc
> │   ├── entity
> │   │   └── src
> │   │       └── docs
> │   │           └── asciidoc
> │   │               ├── entity.adoc
> │   │               └── _include
> │   │                   ├── entity-conditions-api.adoc
> │   │                   ├── entity-engine-intro.adoc
> │   │                   └── mapping-new-database.adoc
> │   └── widget
> │       └── src
> │           └── docs
> │               └── asciidoc
> │                   ├── _include
> │                   │   ├── form-widgets.adoc
> │                   │   ├── screen-widgets.adoc
> │                   │   └── widget-system-intro.adoc
> │                   └── widget.adoc
> ├── ofbiz-manual.adoc
> ├── plugins
> │   └── example
> │       └── src
> │           └── docs
> │               └── asciidoc
> │                   ├── example.adoc
> │                   └── _include
> │                       ├── example-intro.adoc
> │                       └── extending-example-widgets.adoc
> └── themes
>     └── common-theme
>         └── src
>             └── docs
>                 └── asciidoc
>                     ├── common-theme.adoc
>                     └── _include
>                         ├── ofbiz-themes-intro.adoc
>                         ├── web-assets.adoc
>                         └── why-common-theme.adoc
>
> On Fri, Jan 19, 2018 at 4:27 PM, Jacques Le Roux
> <[hidden email]> wrote:
> > Hi Sharan, Craig,
> >
> > We already have a document that consolidates many smaller documents into
> > itself, but as said Sharan in another reply it got not much attention
> > because it was maybe not statisfying (though had interesting info)
> >
> > https://demo-trunk.ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_HTML
> >
> > My 2cts
> >
> > Jacques
> >
> >
> >
> > Le 18/01/2018 à 13:31, Sharan Foga a écrit :
> >>
> >> Hi Craig
> >>
> >> Generally I was thinking about how it was going to be laid out. So if you
> >> think about one big consolidated OFBiz Guide that contains both technical
> >> and user guide info, then what would that look like? How would you structure
> >> the one consolidated output?
> >>
> >> I don't think that it would necessarily need to mirror the exact structure
> >> of the menus - it just depends on how it's linked to the overall process (if
> >> you are thinking user docs). Also some of the things we need to write about
> >> won't appear anywhere in the menus - so we'll need a general place for that.
> >>
> >> My comment was also about the format of each of the source documents to
> >> ensure consistency. Since we are going to be consolidating many smaller
> >> documents into one big one, so it needs to look like they belong together.
> >>
> >> Hope that makes it clearer.
> >>
> >> Thanks
> >> Sharan
> >>
> >> On 2018-01-17 16:08, Craig Parker <[hidden email]> wrote:
> >>>
> >>> I think the doc structure ought to mirror the menu in the software, or
> >>> are you talking about how a doc itself is laid out?
> >>>
> >>>
> >>> On 01/17/2018 09:25 AM, Sharan Foga wrote:
> >>>>
> >>>> Hi Taher
> >>>>
> >>>> Great work! I tried it out and found it simple and easy to use (and
> >>>> write!). When can we start writing ? :-)
> >>>>
> >>>> I was thinking to start with basic descriptions of each of the
> >>>> applications, then see how it evolves from there. We can maybe recover some
> >>>> documentation content from various sources including our existing online
> >>>> help system and the wiki.
> >>>>
> >>>> The documentation structure will maybe need some thought, and we may
> >>>> need to sort out some common template or guidelines around it.
> >>>>
> >>>> Thanks
> >>>> Sharan
> >>>>
> >>>> On 2018-01-14 12:33, "Sharan Foga"<[hidden email]> wrote:
> >>>>>
> >>>>> Excellent news Taher!
> >>>>>
> >>>>> Thanks very much for your effort on this. I'll aim to try it out this
> >>>>> week and come back with any feedback.
> >>>>>
> >>>>> Thanks
> >>>>> Sharan
> >>>>>
> >>>>> On 2018-01-12 17:36, Taher Alkhateeb <[hidden email]>
> >>>>> wrote:
> >>>>>>
> >>>>>> Hello everyone,
> >>>>>>
> >>>>>> Sorry for the delay on my part, I got a little preoccupied. Anyway, I
> >>>>>> have a small patch in [1] that provides the PoC for integrating
> >>>>>> asciidoctor with OFBiz. I also provided in the the JIRA [1]
> >>>>>> instructions on how to run it. Essentially, this allows you to create
> >>>>>> documentation for any component by simply creating a src/docs/asciidoc
> >>>>>> directory and putting files inside.
> >>>>>>
> >>>>>> This solution is flexible and allows us to build bigger designs on top
> >>>>>> of it. Please review it and tell me if you like the general design.
> >>>>>>
> >>>>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
> >>>>>>
> >>>>>> On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
> >>>>>> <[hidden email]> wrote:
> >>>>>>>
> >>>>>>> Hello Folks,
> >>>>>>>
> >>>>>>> We've had this discussion multiple times in the past, but I think I
> >>>>>>> have a more concrete idea this time for solving this problem. In the
> >>>>>>> past few weeks we've been working internally in Pythys to figure out
> >>>>>>> the best way to write and distribute documentation, and I think most
> >>>>>>> of that is applicable to OFBiz.
> >>>>>>>
> >>>>>>> In a nutshell, here is the idea (practically) for how to proceed:
> >>>>>>>
> >>>>>>> - The documentation language to use is Asciidoc
> >>>>>>> - The documentation tool is Asciidoctor
> >>>>>>> - Publishing happens through Gradle using the asciidoctor gradle
> >>>>>>> plugin (not the OFBiz framework or anything else).
> >>>>>>> - The only place where we write documentation is inside the code base
> >>>>>>> - Every component contains its own documentation
> >>>>>>> - General documentation goes to either a standalone directory or a
> >>>>>>> generic component like common or base
> >>>>>>> - As much as possible, documentation files are small and focused on
> >>>>>>> one topic. And then other longer documents are constructed from these
> >>>>>>> snippets of documentation.
> >>>>>>> - We publish to all formats including PDF for users, or HTML for
> >>>>>>> embedded help and wiki pages. So OFBiz does not parse docbook for its
> >>>>>>> help system, instead it just renders generated HTML.
> >>>>>>>
> >>>>>>> As I've worked extensively with Asciidoc I find it easy to pickup
> >>>>>>> (like markdown) but also modular (like docbook and dita). It's also
> >>>>>>> neat that you can sprinkle variables all around in your document so
> >>>>>>> that update is no longer a painful grepping process.
> >>>>>>>
> >>>>>>> Would love to hear your thoughts on this.
> >>>>>>>
> >>>>>>> Cheers,
> >>>>>>>
> >>>>>>> Taher Alkhateeb
> >>>
> >>>
> >
>

[Michael Brohl-3]

+1

with a small modification: I don't think we'll need a two-folder
structure /docs/asciidoc, only /docs should be sufficient, no?

Regards,

Michael


Am 25.01.18 um 15:00 schrieb Sharan Foga:

> Hi Taher
>
> The picture helps :-) I had to do a bit of a double-take but I get it now and a big +1
>
> I like what you are suggesting – very nice. It is not entirely following the  menu structure (which is good) instead it is looking at the individual topics. This means that we can make the main document flow a lot easier than simply following what we have in the menus. (e.g We know that you can get to the same place from by different routes on the menus and screens, so focussing on the topic itself will help that.)
>
> I think this will give us the flexibility we need. A standard structure helps people know where to put things.
>
> Thanks
> Sharan
>
> On 2018/01/25 11:37:02, Taher Alkhateeb <[hidden email]> wrote:
>> Hi Everyone,
>>
>> So after a little bit of thinking, I came up with an example file
>> structure for OFBiz documentation which is listed below. The full
>> OFBiz manual simply points to all the parts in applications,
>> framework, and themes to complete the documentation. Any ideas or
>> feedback is welcomed.
>>
>> A few points to note:
>> - Gradle by default ignores any files in the _include sub directory
>> and so it will only publish the outer document.
>> - This way, we can publish per component (in isolation) or the whole
>> documentation by simply publishing the ofbiz-manual.adoc file
>> - We can further branch out the documentation as needed.
>>
>> ofbiz
>> ├── applications
>> │   ├── accounting
>> │   │   └── src
>> │   │       └── docs
>> │   │           └── asciidoc
>> │   │               ├── accounting.adoc
>> │   │               └── _include
>> │   │                   ├── accounting-intro.adoc
>> │   │                   ├── budgets.adoc
>> │   │                   ├── invoices.adoc
>> │   │                   ├── payments.adoc
>> │   │                   └── understanding-general-ledger.adoc
>> │   └── humanres
>> │       └── src
>> │           └── docs
>> │               └── asciidoc
>> │                   ├── humanres.adoc
>> │                   └── _include
>> │                       ├── employee-evaluations.adoc
>> │                       ├── human-resources-intro.adoc
>> │                       └── punch-in-punch-out.adoc
>> ├── framework
>> │   ├── base
>> │   │   └── src
>> │   │       └── docs
>> │   │           └── asciidoc
>> │   │               ├── base.adoc
>> │   │               └── _include
>> │   │                   ├── containers.adoc
>> │   │                   ├── framework-intro.adoc
>> │   │                   └── loading-components.adoc
>> │   ├── entity
>> │   │   └── src
>> │   │       └── docs
>> │   │           └── asciidoc
>> │   │               ├── entity.adoc
>> │   │               └── _include
>> │   │                   ├── entity-conditions-api.adoc
>> │   │                   ├── entity-engine-intro.adoc
>> │   │                   └── mapping-new-database.adoc
>> │   └── widget
>> │       └── src
>> │           └── docs
>> │               └── asciidoc
>> │                   ├── _include
>> │                   │   ├── form-widgets.adoc
>> │                   │   ├── screen-widgets.adoc
>> │                   │   └── widget-system-intro.adoc
>> │                   └── widget.adoc
>> ├── ofbiz-manual.adoc
>> ├── plugins
>> │   └── example
>> │       └── src
>> │           └── docs
>> │               └── asciidoc
>> │                   ├── example.adoc
>> │                   └── _include
>> │                       ├── example-intro.adoc
>> │                       └── extending-example-widgets.adoc
>> └── themes
>>      â””── common-theme
>>          â””── src
>>              â””── docs
>>                  â””── asciidoc
>>                      â”œâ”€â”€ common-theme.adoc
>>                      â””── _include
>>                          â”œâ”€â”€ ofbiz-themes-intro.adoc
>>                          â”œâ”€â”€ web-assets.adoc
>>                          â””── why-common-theme.adoc
>>
>> On Fri, Jan 19, 2018 at 4:27 PM, Jacques Le Roux
>> <[hidden email]> wrote:
>>> Hi Sharan, Craig,
>>>
>>> We already have a document that consolidates many smaller documents into
>>> itself, but as said Sharan in another reply it got not much attention
>>> because it was maybe not statisfying (though had interesting info)
>>>
>>> https://demo-trunk.ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_HTML
>>>
>>> My 2cts
>>>
>>> Jacques
>>>
>>>
>>>
>>> Le 18/01/2018 à 13:31, Sharan Foga a écrit :
>>>> Hi Craig
>>>>
>>>> Generally I was thinking about how it was going to be laid out. So if you
>>>> think about one big consolidated OFBiz Guide that contains both technical
>>>> and user guide info, then what would that look like? How would you structure
>>>> the one consolidated output?
>>>>
>>>> I don't think that it would necessarily need to mirror the exact structure
>>>> of the menus - it just depends on how it's linked to the overall process (if
>>>> you are thinking user docs). Also some of the things we need to write about
>>>> won't appear anywhere in the menus - so we'll need a general place for that.
>>>>
>>>> My comment was also about the format of each of the source documents to
>>>> ensure consistency. Since we are going to be consolidating many smaller
>>>> documents into one big one, so it needs to look like they belong together.
>>>>
>>>> Hope that makes it clearer.
>>>>
>>>> Thanks
>>>> Sharan
>>>>
>>>> On 2018-01-17 16:08, Craig Parker <[hidden email]> wrote:
>>>>> I think the doc structure ought to mirror the menu in the software, or
>>>>> are you talking about how a doc itself is laid out?
>>>>>
>>>>>
>>>>> On 01/17/2018 09:25 AM, Sharan Foga wrote:
>>>>>> Hi Taher
>>>>>>
>>>>>> Great work! I tried it out and found it simple and easy to use (and
>>>>>> write!). When can we start writing ? :-)
>>>>>>
>>>>>> I was thinking to start with basic descriptions of each of the
>>>>>> applications, then see how it evolves from there. We can maybe recover some
>>>>>> documentation content from various sources including our existing online
>>>>>> help system and the wiki.
>>>>>>
>>>>>> The documentation structure will maybe need some thought, and we may
>>>>>> need to sort out some common template or guidelines around it.
>>>>>>
>>>>>> Thanks
>>>>>> Sharan
>>>>>>
>>>>>> On 2018-01-14 12:33, "Sharan Foga"<[hidden email]> wrote:
>>>>>>> Excellent news Taher!
>>>>>>>
>>>>>>> Thanks very much for your effort on this. I'll aim to try it out this
>>>>>>> week and come back with any feedback.
>>>>>>>
>>>>>>> Thanks
>>>>>>> Sharan
>>>>>>>
>>>>>>> On 2018-01-12 17:36, Taher Alkhateeb <[hidden email]>
>>>>>>> wrote:
>>>>>>>> Hello everyone,
>>>>>>>>
>>>>>>>> Sorry for the delay on my part, I got a little preoccupied. Anyway, I
>>>>>>>> have a small patch in [1] that provides the PoC for integrating
>>>>>>>> asciidoctor with OFBiz. I also provided in the the JIRA [1]
>>>>>>>> instructions on how to run it. Essentially, this allows you to create
>>>>>>>> documentation for any component by simply creating a src/docs/asciidoc
>>>>>>>> directory and putting files inside.
>>>>>>>>
>>>>>>>> This solution is flexible and allows us to build bigger designs on top
>>>>>>>> of it. Please review it and tell me if you like the general design.
>>>>>>>>
>>>>>>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>>>>>>>>
>>>>>>>> On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
>>>>>>>> <[hidden email]> wrote:
>>>>>>>>> Hello Folks,
>>>>>>>>>
>>>>>>>>> We've had this discussion multiple times in the past, but I think I
>>>>>>>>> have a more concrete idea this time for solving this problem. In the
>>>>>>>>> past few weeks we've been working internally in Pythys to figure out
>>>>>>>>> the best way to write and distribute documentation, and I think most
>>>>>>>>> of that is applicable to OFBiz.
>>>>>>>>>
>>>>>>>>> In a nutshell, here is the idea (practically) for how to proceed:
>>>>>>>>>
>>>>>>>>> - The documentation language to use is Asciidoc
>>>>>>>>> - The documentation tool is Asciidoctor
>>>>>>>>> - Publishing happens through Gradle using the asciidoctor gradle
>>>>>>>>> plugin (not the OFBiz framework or anything else).
>>>>>>>>> - The only place where we write documentation is inside the code base
>>>>>>>>> - Every component contains its own documentation
>>>>>>>>> - General documentation goes to either a standalone directory or a
>>>>>>>>> generic component like common or base
>>>>>>>>> - As much as possible, documentation files are small and focused on
>>>>>>>>> one topic. And then other longer documents are constructed from these
>>>>>>>>> snippets of documentation.
>>>>>>>>> - We publish to all formats including PDF for users, or HTML for
>>>>>>>>> embedded help and wiki pages. So OFBiz does not parse docbook for its
>>>>>>>>> help system, instead it just renders generated HTML.
>>>>>>>>>
>>>>>>>>> As I've worked extensively with Asciidoc I find it easy to pickup
>>>>>>>>> (like markdown) but also modular (like docbook and dita). It's also
>>>>>>>>> neat that you can sprinkle variables all around in your document so
>>>>>>>>> that update is no longer a painful grepping process.
>>>>>>>>>
>>>>>>>>> Would love to hear your thoughts on this.
>>>>>>>>>
>>>>>>>>> Cheers,
>>>>>>>>>
>>>>>>>>> Taher Alkhateeb
>>>>>

[Paul Foxworthy]

On 26 January 2018 at 19:53, Michael Brohl <[hidden email]> wrote:


> with a small modification: I don't think we'll need a two-folder structure
> /docs/asciidoc, only /docs should be sufficient, no?
>

Hi Michael,

We have streamlined the build system in other places by having folders for
the source language: groovyScripts, minilang, src/main/java .

It means Groovy and other build tools can have default rules for what to do
with the contents of a language folder, and allows for the possibility of
other languages in future if necessary.

The extra layer is only a minor nuisance. I think I'd prefer to keep it.
What do you see as the disadvantages?

Cheers

Paul Foxworthy

--
Coherent Software Australia Pty Ltd
PO Box 2773
Cheltenham Vic 3192
Australia

Phone: [phone]
Web: http://www.coherentsoftware.com.au/
Email: [hidden email]

[Michael Brohl-3]

Hi Paul,

this is only a minor point for me, it just saves one folder/structure level.

If we want to stay open for other documentation frameworks in the
future, it might be better to keep the proposed structure.

Best regards,

Michael


Am 28.01.18 um 02:54 schrieb Paul Foxworthy:

> On 26 January 2018 at 19:53, Michael Brohl <[hidden email]> wrote:
>
>
>> with a small modification: I don't think we'll need a two-folder structure
>> /docs/asciidoc, only /docs should be sufficient, no?
>>
> Hi Michael,
>
> We have streamlined the build system in other places by having folders for
> the source language: groovyScripts, minilang, src/main/java .
>
> It means Groovy and other build tools can have default rules for what to do
> with the contents of a language folder, and allows for the possibility of
> other languages in future if necessary.
>
> The extra layer is only a minor nuisance. I think I'd prefer to keep it.
> What do you see as the disadvantages?
>
> Cheers
>
> Paul Foxworthy
>

[taher]

Like Michael I think it is also a minor point. The reason I chose this
structure is because it is the default one for asciidoctor and is flexible
for the future, so Paul also makes a good point. Any structure is fine by
me, the real important work is getting the documentation right which is
very exciting to me.

I will create a patch soon for a base level structure and publishing
options for both HTML and PDF. It would be fantastic if we can unify _all_
of our documentation here including stuff currently in the wiki. This way
any changes to code are reflected (probably in the same commit) with the
relevant documentation.

I think we should start to consider maybe forming a team willing to help.
This is a big, but extremely important thing to have. If we do this right
then I think adoption rates would increase and our community would get
larger.

On Jan 28, 2018 12:19 PM, "Michael Brohl" <[hidden email]> wrote:

Hi Paul,

this is only a minor point for me, it just saves one folder/structure level.

If we want to stay open for other documentation frameworks in the future,
it might be better to keep the proposed structure.

Best regards,

Michael


Am 28.01.18 um 02:54 schrieb Paul Foxworthy:

On 26 January 2018 at 19:53, Michael Brohl <[hidden email]> wrote:

>
>
> with a small modification: I don't think we'll need a two-folder structure
>> /docs/asciidoc, only /docs should be sufficient, no?
>>
>> Hi Michael,
>
> We have streamlined the build system in other places by having folders for
> the source language: groovyScripts, minilang, src/main/java .
>
> It means Groovy and other build tools can have default rules for what to do
> with the contents of a language folder, and allows for the possibility of
> other languages in future if necessary.
>
> The extra layer is only a minor nuisance. I think I'd prefer to keep it.
> What do you see as the disadvantages?
>
> Cheers
>
> Paul Foxworthy
>
>

[Jacques Le Roux]

\o/

Jacques


Le 28/01/2018 à 11:12, Taher Alkhateeb a écrit :

> Like Michael I think it is also a minor point. The reason I chose this
> structure is because it is the default one for asciidoctor and is flexible
> for the future, so Paul also makes a good point. Any structure is fine by
> me, the real important work is getting the documentation right which is
> very exciting to me.
>
> I will create a patch soon for a base level structure and publishing
> options for both HTML and PDF. It would be fantastic if we can unify _all_
> of our documentation here including stuff currently in the wiki. This way
> any changes to code are reflected (probably in the same commit) with the
> relevant documentation.
>
> I think we should start to consider maybe forming a team willing to help.
> This is a big, but extremely important thing to have. If we do this right
> then I think adoption rates would increase and our community would get
> larger.
>
> On Jan 28, 2018 12:19 PM, "Michael Brohl" <[hidden email]> wrote:
>
> Hi Paul,
>
> this is only a minor point for me, it just saves one folder/structure level.
>
> If we want to stay open for other documentation frameworks in the future,
> it might be better to keep the proposed structure.
>
> Best regards,
>
> Michael
>
>
> Am 28.01.18 um 02:54 schrieb Paul Foxworthy:
>
> On 26 January 2018 at 19:53, Michael Brohl <[hidden email]> wrote:
>>
>> with a small modification: I don't think we'll need a two-folder structure
>>> /docs/asciidoc, only /docs should be sufficient, no?
>>>
>>> Hi Michael,
>> We have streamlined the build system in other places by having folders for
>> the source language: groovyScripts, minilang, src/main/java .
>>
>> It means Groovy and other build tools can have default rules for what to do
>> with the contents of a language folder, and allows for the possibility of
>> other languages in future if necessary.
>>
>> The extra layer is only a minor nuisance. I think I'd prefer to keep it.
>> What do you see as the disadvantages?
>>
>> Cheers
>>
>> Paul Foxworthy
>>
>>

[Sharan Foga]

Hi Taher

I think a documentation team would be a great idea. There are people that have indicated that they'd like to help out with documentation tasks on the user list so that is where I'd recruit some people from. As long as people know what they need to do to create the patches then it will become a funnel process of getting it committed.

We need a plan to consolidate the information sitting in the wiki and getting it put into the documentation framework (and this work will then significantly clear up the wiki!).

My availability is pretty bad this week so hope to pick this up again or start the recruitment campaign next week :-)

Thanks
Sharan

On 2018/01/28 10:12:41, Taher Alkhateeb <[hidden email]> wrote:

> Like Michael I think it is also a minor point. The reason I chose this
> structure is because it is the default one for asciidoctor and is flexible
> for the future, so Paul also makes a good point. Any structure is fine by
> me, the real important work is getting the documentation right which is
> very exciting to me.
>
> I will create a patch soon for a base level structure and publishing
> options for both HTML and PDF. It would be fantastic if we can unify _all_
> of our documentation here including stuff currently in the wiki. This way
> any changes to code are reflected (probably in the same commit) with the
> relevant documentation.
>
> I think we should start to consider maybe forming a team willing to help.
> This is a big, but extremely important thing to have. If we do this right
> then I think adoption rates would increase and our community would get
> larger.
>
> On Jan 28, 2018 12:19 PM, "Michael Brohl" <[hidden email]> wrote:
>
> Hi Paul,
>
> this is only a minor point for me, it just saves one folder/structure level.
>
> If we want to stay open for other documentation frameworks in the future,
> it might be better to keep the proposed structure.
>
> Best regards,
>
> Michael
>
>
> Am 28.01.18 um 02:54 schrieb Paul Foxworthy:
>
> On 26 January 2018 at 19:53, Michael Brohl <[hidden email]> wrote:
> >
> >
> > with a small modification: I don't think we'll need a two-folder structure
> >> /docs/asciidoc, only /docs should be sufficient, no?
> >>
> >> Hi Michael,
> >
> > We have streamlined the build system in other places by having folders for
> > the source language: groovyScripts, minilang, src/main/java .
> >
> > It means Groovy and other build tools can have default rules for what to do
> > with the contents of a language folder, and allows for the possibility of
> > other languages in future if necessary.
> >
> > The extra layer is only a minor nuisance. I think I'd prefer to keep it.
> > What do you see as the disadvantages?
> >
> > Cheers
> >
> > Paul Foxworthy
> >
> >
>

[taher]

Hello documentation team and everyone

I have created a slightly modified design of the documentation
framework with some sample contents in [1]. I highlight the changes
below:
- Created a new top-level directory called "docs/asciidoc". The reason
is so that we have more than one possible manual.
- Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc
- Created "Apache OFBiz Developer Manual" in docs/asciidoc/developer-manual.adoc
- Created a sample document in the accounting component to show how
documents are linked together.
- Used a special directive called "leveloffset" in the include
directive. This directive shifts the headers of the included document
(H2 becomes H3, and so on) so that sub-sections can be published
separately.
- Created a task called generateOfbizDocumentation to generate the
documentation (both PDF and HTML) for framework + core apps
- Created a task called generatePluginDocumentation
-PpluginId=whatever to generate the documentation for a single plugin.

That's it. It's simple, easy to understand and I think you might like
it. Any feedback is welcome, and I'll talk to you soon over Skype.

[1] https://issues.apache.org/jira/browse/OFBIZ-9873

On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga <[hidden email]> wrote:

> Hi Taher
>
> I think a documentation team would be a great idea. There are people that have indicated that they'd like to help out with documentation tasks on the user list so that is where I'd recruit some people from. As long as people know what they need to do to create the patches then it will become a funnel process of getting it committed.
>
> We need a plan to consolidate the information sitting in the wiki and getting it put into the documentation framework (and this work will then significantly clear up the wiki!).
>
> My availability is pretty bad this week so hope to pick this up again or start the recruitment campaign next week :-)
>
> Thanks
> Sharan
>
> On 2018/01/28 10:12:41, Taher Alkhateeb <[hidden email]> wrote:
>> Like Michael I think it is also a minor point. The reason I chose this
>> structure is because it is the default one for asciidoctor and is flexible
>> for the future, so Paul also makes a good point. Any structure is fine by
>> me, the real important work is getting the documentation right which is
>> very exciting to me.
>>
>> I will create a patch soon for a base level structure and publishing
>> options for both HTML and PDF. It would be fantastic if we can unify _all_
>> of our documentation here including stuff currently in the wiki. This way
>> any changes to code are reflected (probably in the same commit) with the
>> relevant documentation.
>>
>> I think we should start to consider maybe forming a team willing to help.
>> This is a big, but extremely important thing to have. If we do this right
>> then I think adoption rates would increase and our community would get
>> larger.
>>
>> On Jan 28, 2018 12:19 PM, "Michael Brohl" <[hidden email]> wrote:
>>
>> Hi Paul,
>>
>> this is only a minor point for me, it just saves one folder/structure level.
>>
>> If we want to stay open for other documentation frameworks in the future,
>> it might be better to keep the proposed structure.
>>
>> Best regards,
>>
>> Michael
>>
>>
>> Am 28.01.18 um 02:54 schrieb Paul Foxworthy:
>>
>> On 26 January 2018 at 19:53, Michael Brohl <[hidden email]> wrote:
>> >
>> >
>> > with a small modification: I don't think we'll need a two-folder structure
>> >> /docs/asciidoc, only /docs should be sufficient, no?
>> >>
>> >> Hi Michael,
>> >
>> > We have streamlined the build system in other places by having folders for
>> > the source language: groovyScripts, minilang, src/main/java .
>> >
>> > It means Groovy and other build tools can have default rules for what to do
>> > with the contents of a language folder, and allows for the possibility of
>> > other languages in future if necessary.
>> >
>> > The extra layer is only a minor nuisance. I think I'd prefer to keep it.
>> > What do you see as the disadvantages?
>> >
>> > Cheers
>> >
>> > Paul Foxworthy
>> >
>> >
>>