[Discussion] documentation framework for OFBiz

[taher]

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

Hi Taher

It's great that this conversation has started again. It would be great
to actually start to do something about the integrated help system
within OFBiz itself. We have found limitations with the docbook
implementation we have, so now have a better idea of what we want to
achieve.

In the past we've talked a lot about DITA but to me it seemed a lot more
complex to understand, structure and generally get started. I've briefly
played about with Ascidoc and it seems pretty simple enough to get the
hang of and that to me is an important thing. I also like the idea of
being able to render multiple formats (and it would be good to make them
look nicer and easier to read).

Getting a good and functioning help framework into our codebase is long
overdue and I'm sure will add some great benefits and also encourage
documentation contributions from our community.

Big +1 from me!

Thanks
Sharan


On 17/10/17 10:01, Taher Alkhateeb 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]

Big +1 for this initiative!

I have not much to add to Taher's proposal and Sharan's viewpoint.

I assume that we can use any Asciidoc editor and need not to use
Asciidoctor?

I think we have to decide what we will do with our Wiki based
documentation then. If we have up-to-date documentation in the
components and can generate up-to-date documentation every night, pretty
much of the Wiki documentation would be obsolete. A simple link to the
generated documentation would be enough, right?

For new code in framework and plugins, I would strongly recommend to
have mandatory documentation as part of the first commit to the codebase
to assure a good initial start.

I think we should just start with a proof-of-concept by moving some
small part of the documentation to Asciidoc and into the codebase.

Would be a great starting point for new contributors also.

Best regards,

Michael


Am 17.10.17 um 10:30 schrieb Sharan Foga:

> Hi Taher
>
> It's great that this conversation has started again. It would be great
> to actually start to do something about the integrated help system
> within OFBiz itself. We have found limitations with the docbook
> implementation we have, so now have a better idea of what we want to
> achieve.
>
> In the past we've talked a lot about DITA but to me it seemed a lot
> more complex to understand, structure and generally get started. I've
> briefly played about with Ascidoc and it seems pretty simple enough to
> get the hang of and that to me is an important thing. I also like the
> idea of being able to render multiple formats (and it would be good to
> make them look nicer and easier to read).
>
> Getting a good and functioning help framework into our codebase is
> long overdue and I'm sure will add some great benefits and also
> encourage documentation contributions from our community.
>
> Big +1 from me!
>
> Thanks
> Sharan
>
>
> On 17/10/17 10:01, Taher Alkhateeb 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]

Yes thanks Taher to have picked this again,

I agree with all what have been said so far.

You know my preference for asscidoc and asciidoctor. Using the asciidoctor Gradle plugin seems logical to me.

I'm all for having all the documentation inside the source. I had even created a Jira for that https://issues.apache.org/jira/browse/OFBIZ-9423

Questions:

 1. Should we continue to provide an online help? Would we reuse/upgrade the current one?
 2. Where to put the common documentation? In common or commonext component or in a new documentation folder? Later seems easier for newbies, name
    says all.
 3. I use pandoc to create (from some .md files) md.html files in tools\wiki-files imported in wiki pages. I regularly use a .bat for that. Would we
    replace also our current .md files?

Jacques


Le 17/10/2017 à 11:25, Michael Brohl a écrit :

> Big +1 for this initiative!
>
> I have not much to add to Taher's proposal and Sharan's viewpoint.
>
> I assume that we can use any Asciidoc editor and need not to use Asciidoctor?
>
> I think we have to decide what we will do with our Wiki based documentation then. If we have up-to-date documentation in the components and can
> generate up-to-date documentation every night, pretty much of the Wiki documentation would be obsolete. A simple link to the generated documentation
> would be enough, right?
>
> For new code in framework and plugins, I would strongly recommend to have mandatory documentation as part of the first commit to the codebase to
> assure a good initial start.
>
> I think we should just start with a proof-of-concept by moving some small part of the documentation to Asciidoc and into the codebase.
>
> Would be a great starting point for new contributors also.
>
> Best regards,
>
> Michael
>
>
> Am 17.10.17 um 10:30 schrieb Sharan Foga:
>> Hi Taher
>>
>> It's great that this conversation has started again. It would be great to actually start to do something about the integrated help system within
>> OFBiz itself. We have found limitations with the docbook implementation we have, so now have a better idea of what we want to achieve.
>>
>> In the past we've talked a lot about DITA but to me it seemed a lot more complex to understand, structure and generally get started. I've briefly
>> played about with Ascidoc and it seems pretty simple enough to get the hang of and that to me is an important thing. I also like the idea of being
>> able to render multiple formats (and it would be good to make them look nicer and easier to read).
>>
>> Getting a good and functioning help framework into our codebase is long overdue and I'm sure will add some great benefits and also encourage
>> documentation contributions from our community.
>>
>> Big +1 from me!
>>
>> Thanks
>> Sharan
>>
>>
>> On 17/10/17 10:01, Taher Alkhateeb 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

I would say the first and easier focus is to complete the online help. Telling people how to use the screens and applications is a basic requirement that we haven't fulfilled for OFBiz yet.  Once we have that then we can see how it can be expanded to incorporate more general details. I think the issue we have had over the years is that OFBiz is so big that it's difficult to know where to start.

At least if we can give people information about the application they are using, and how to use the screens, then that will give them enough to get going. For content we could review the existing help that we have and update it into a standard format or template so that it is consistent.

We may also find that we still need the wiki for something so let's see what happens

Thanks
Sharan

On 2017-10-17 13:21, Jacques Le Roux <[hidden email]> wrote:

> Yes thanks Taher to have picked this again,
>
> I agree with all what have been said so far.
>
> You know my preference for asscidoc and asciidoctor. Using the asciidoctor Gradle plugin seems logical to me.
>
> I'm all for having all the documentation inside the source. I had even created a Jira for that https://issues.apache.org/jira/browse/OFBIZ-9423
>
> Questions:
>
>  1. Should we continue to provide an online help? Would we reuse/upgrade the current one?
>  2. Where to put the common documentation? In common or commonext component or in a new documentation folder? Later seems easier for newbies, name
>     says all.
>  3. I use pandoc to create (from some .md files) md.html files in tools\wiki-files imported in wiki pages. I regularly use a .bat for that. Would we
>     replace also our current .md files?
>
> Jacques
>
>
> Le 17/10/2017 à 11:25, Michael Brohl a écrit :
> > Big +1 for this initiative!
> >
> > I have not much to add to Taher's proposal and Sharan's viewpoint.
> >
> > I assume that we can use any Asciidoc editor and need not to use Asciidoctor?
> >
> > I think we have to decide what we will do with our Wiki based documentation then. If we have up-to-date documentation in the components and can
> > generate up-to-date documentation every night, pretty much of the Wiki documentation would be obsolete. A simple link to the generated documentation
> > would be enough, right?
> >
> > For new code in framework and plugins, I would strongly recommend to have mandatory documentation as part of the first commit to the codebase to
> > assure a good initial start.
> >
> > I think we should just start with a proof-of-concept by moving some small part of the documentation to Asciidoc and into the codebase.
> >
> > Would be a great starting point for new contributors also.
> >
> > Best regards,
> >
> > Michael
> >
> >
> > Am 17.10.17 um 10:30 schrieb Sharan Foga:
> >> Hi Taher
> >>
> >> It's great that this conversation has started again. It would be great to actually start to do something about the integrated help system within
> >> OFBiz itself. We have found limitations with the docbook implementation we have, so now have a better idea of what we want to achieve.
> >>
> >> In the past we've talked a lot about DITA but to me it seemed a lot more complex to understand, structure and generally get started. I've briefly
> >> played about with Ascidoc and it seems pretty simple enough to get the hang of and that to me is an important thing. I also like the idea of being
> >> able to render multiple formats (and it would be good to make them look nicer and easier to read).
> >>
> >> Getting a good and functioning help framework into our codebase is long overdue and I'm sure will add some great benefits and also encourage
> >> documentation contributions from our community.
> >>
> >> Big +1 from me!
> >>
> >> Thanks
> >> Sharan
> >>
> >>
> >> On 17/10/17 10:01, Taher Alkhateeb 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,

Yes I'm pretty sure we will still need the wiki. For technical points which don't specially fit in source and also some kind of user documentation,
but the less the better.

Jacques


Le 18/10/2017 à 10:28, Sharan Foga a écrit :

> Hi
>
> I would say the first and easier focus is to complete the online help. Telling people how to use the screens and applications is a basic requirement that we haven't fulfilled for OFBiz yet.  Once we have that then we can see how it can be expanded to incorporate more general details. I think the issue we have had over the years is that OFBiz is so big that it's difficult to know where to start.
>
> At least if we can give people information about the application they are using, and how to use the screens, then that will give them enough to get going. For content we could review the existing help that we have and update it into a standard format or template so that it is consistent.
>
> We may also find that we still need the wiki for something so let's see what happens
>
> Thanks
> Sharan
>
> On 2017-10-17 13:21, Jacques Le Roux <[hidden email]> wrote:
>> Yes thanks Taher to have picked this again,
>>
>> I agree with all what have been said so far.
>>
>> You know my preference for asscidoc and asciidoctor. Using the asciidoctor Gradle plugin seems logical to me.
>>
>> I'm all for having all the documentation inside the source. I had even created a Jira for that https://issues.apache.org/jira/browse/OFBIZ-9423
>>
>> Questions:
>>
>>   1. Should we continue to provide an online help? Would we reuse/upgrade the current one?
>>   2. Where to put the common documentation? In common or commonext component or in a new documentation folder? Later seems easier for newbies, name
>>      says all.
>>   3. I use pandoc to create (from some .md files) md.html files in tools\wiki-files imported in wiki pages. I regularly use a .bat for that. Would we
>>      replace also our current .md files?
>>
>> Jacques
>>
>>
>> Le 17/10/2017 à 11:25, Michael Brohl a écrit :
>>> Big +1 for this initiative!
>>>
>>> I have not much to add to Taher's proposal and Sharan's viewpoint.
>>>
>>> I assume that we can use any Asciidoc editor and need not to use Asciidoctor?
>>>
>>> I think we have to decide what we will do with our Wiki based documentation then. If we have up-to-date documentation in the components and can
>>> generate up-to-date documentation every night, pretty much of the Wiki documentation would be obsolete. A simple link to the generated documentation
>>> would be enough, right?
>>>
>>> For new code in framework and plugins, I would strongly recommend to have mandatory documentation as part of the first commit to the codebase to
>>> assure a good initial start.
>>>
>>> I think we should just start with a proof-of-concept by moving some small part of the documentation to Asciidoc and into the codebase.
>>>
>>> Would be a great starting point for new contributors also.
>>>
>>> Best regards,
>>>
>>> Michael
>>>
>>>
>>> Am 17.10.17 um 10:30 schrieb Sharan Foga:
>>>> Hi Taher
>>>>
>>>> It's great that this conversation has started again. It would be great to actually start to do something about the integrated help system within
>>>> OFBiz itself. We have found limitations with the docbook implementation we have, so now have a better idea of what we want to achieve.
>>>>
>>>> In the past we've talked a lot about DITA but to me it seemed a lot more complex to understand, structure and generally get started. I've briefly
>>>> played about with Ascidoc and it seems pretty simple enough to get the hang of and that to me is an important thing. I also like the idea of being
>>>> able to render multiple formats (and it would be good to make them look nicer and easier to read).
>>>>
>>>> Getting a good and functioning help framework into our codebase is long overdue and I'm sure will add some great benefits and also encourage
>>>> documentation contributions from our community.
>>>>
>>>> Big +1 from me!
>>>>
>>>> Thanks
>>>> Sharan
>>>>
>>>>
>>>> On 17/10/17 10:01, Taher Alkhateeb 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]

Thank you folks for your feedback. Based on everyone's input, I think
perhaps a good way to move forward is by creating a JIRA and making a
patch for a PoC.

I think altering the OFBiz help system for now might be a bigger task,
so for a start, I think I will write some documentation in multiple
places and then let gradle consolidate that into an output manual.
Then, based on feedback from you we decide on the next step.

So I will proceed with creating a JIRA for an initial PoC. Again,
thank you for your thoughts, all constructive and valuable.

On Wed, Oct 18, 2017 at 11:47 AM, Jacques Le Roux
<[hidden email]> wrote:

> Hi Sharan,
>
> Yes I'm pretty sure we will still need the wiki. For technical points which
> don't specially fit in source and also some kind of user documentation, but
> the less the better.
>
> Jacques
>
>
> Le 18/10/2017 à 10:28, Sharan Foga a écrit :
>>
>> Hi
>>
>> I would say the first and easier focus is to complete the online help.
>> Telling people how to use the screens and applications is a basic
>> requirement that we haven't fulfilled for OFBiz yet.  Once we have that then
>> we can see how it can be expanded to incorporate more general details. I
>> think the issue we have had over the years is that OFBiz is so big that it's
>> difficult to know where to start.
>>
>> At least if we can give people information about the application they are
>> using, and how to use the screens, then that will give them enough to get
>> going. For content we could review the existing help that we have and update
>> it into a standard format or template so that it is consistent.
>>
>> We may also find that we still need the wiki for something so let's see
>> what happens
>>
>> Thanks
>> Sharan
>>
>> On 2017-10-17 13:21, Jacques Le Roux <[hidden email]> wrote:
>>>
>>> Yes thanks Taher to have picked this again,
>>>
>>> I agree with all what have been said so far.
>>>
>>> You know my preference for asscidoc and asciidoctor. Using the
>>> asciidoctor Gradle plugin seems logical to me.
>>>
>>> I'm all for having all the documentation inside the source. I had even
>>> created a Jira for that https://issues.apache.org/jira/browse/OFBIZ-9423
>>>
>>> Questions:
>>>
>>>   1. Should we continue to provide an online help? Would we reuse/upgrade
>>> the current one?
>>>   2. Where to put the common documentation? In common or commonext
>>> component or in a new documentation folder? Later seems easier for newbies,
>>> name
>>>      says all.
>>>   3. I use pandoc to create (from some .md files) md.html files in
>>> tools\wiki-files imported in wiki pages. I regularly use a .bat for that.
>>> Would we
>>>      replace also our current .md files?
>>>
>>> Jacques
>>>
>>>
>>> Le 17/10/2017 à  11:25, Michael Brohl a écrit :
>>>
>>>> Big +1 for this initiative!
>>>>
>>>> I have not much to add to Taher's proposal and Sharan's viewpoint.
>>>>
>>>> I assume that we can use any Asciidoc editor and need not to use
>>>> Asciidoctor?
>>>>
>>>> I think we have to decide what we will do with our Wiki based
>>>> documentation then. If we have up-to-date documentation in the components
>>>> and can
>>>> generate up-to-date documentation every night, pretty much of the Wiki
>>>> documentation would be obsolete. A simple link to the generated
>>>> documentation
>>>> would be enough, right?
>>>>
>>>> For new code in framework and plugins, I would strongly recommend to
>>>> have mandatory documentation as part of the first commit to the codebase to
>>>> assure a good initial start.
>>>>
>>>> I think we should just start with a proof-of-concept by moving some
>>>> small part of the documentation to Asciidoc and into the codebase.
>>>>
>>>> Would be a great starting point for new contributors also.
>>>>
>>>> Best regards,
>>>>
>>>> Michael
>>>>
>>>>
>>>> Am 17.10.17 um 10:30 schrieb Sharan Foga:
>>>>>
>>>>> Hi Taher
>>>>>
>>>>> It's great that this conversation has started again. It would be great
>>>>> to actually start to do something about the integrated help system within
>>>>> OFBiz itself. We have found limitations with the docbook implementation
>>>>> we have, so now have a better idea of what we want to achieve.
>>>>>
>>>>> In the past we've talked a lot about DITA but to me it seemed a lot
>>>>> more complex to understand, structure and generally get started. I've
>>>>> briefly
>>>>> played about with Ascidoc and it seems pretty simple enough to get the
>>>>> hang of and that to me is an important thing. I also like the idea of being
>>>>> able to render multiple formats (and it would be good to make them look
>>>>> nicer and easier to read).
>>>>>
>>>>> Getting a good and functioning help framework into our codebase is long
>>>>> overdue and I'm sure will add some great benefits and also encourage
>>>>> documentation contributions from our community.
>>>>>
>>>>> Big +1 from me!
>>>>>
>>>>> Thanks
>>>>> Sharan
>>>>>
>>>>>
>>>>> On 17/10/17 10:01, Taher Alkhateeb 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 17 October 2017 at 20:25, Michael Brohl <[hidden email]> wrote:


> I assume that we can use any Asciidoc editor and need not to use
> Asciidoctor?
>

Hi Michael,

Asciidoctor is not an editor, it's a text processor that can convert
AsciiDoc to HTML or DocBook XML. So it's an alternative processor to Pandoc
(https://pandoc.org/).

One of the reasons to choose any wiki-like language (AsciiDoc, Markdown,
etc) is you can use any text editor at all. I use a nice AsciiDoc plugin
for IntelliJ IDEA. Your tastes may vary.

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]

[Jacques Le Roux]

Le 08/11/2017 à 08:25, Paul Foxworthy a écrit :

> On 17 October 2017 at 20:25, Michael Brohl <[hidden email]> wrote:
>
>
>> I assume that we can use any Asciidoc editor and need not to use
>> Asciidoctor?
>>
> Hi Michael,
>
> Asciidoctor is not an editor, it's a text processor that can convert
> AsciiDoc to HTML or DocBook XML. So it's an alternative processor to Pandoc
> (https://pandoc.org/).
>
> One of the reasons to choose any wiki-like language (AsciiDoc, Markdown,
> etc) is you can use any text editor at all. I use a nice AsciiDoc plugin
> for IntelliJ IDEA. Your tastes may vary.
>
> Cheers
>
> Paul Foxworthy
>

Hi Paul,

Do you know if there are there good reasons to favor Asciidoctor over Pandoc?
I'm more in favour of the later because now I know it (thanks to you :)) and especially because it offers so much possibilities, see graph here
https://pandoc.org/
You never know what you will need one day...

Jacques

[taher]

If you check the link you sent, you will notice that asciidoc is not an
input format in pandoc, but rather an ouput format.

On Nov 8, 2017 12:29 PM, "Jacques Le Roux" <[hidden email]>
wrote:

Le 08/11/2017 à 08:25, Paul Foxworthy a écrit :

> On 17 October 2017 at 20:25, Michael Brohl <[hidden email]>
> wrote:
>
>
> I assume that we can use any Asciidoc editor and need not to use
>> Asciidoctor?
>>
>> Hi Michael,
>
> Asciidoctor is not an editor, it's a text processor that can convert
> AsciiDoc to HTML or DocBook XML. So it's an alternative processor to Pandoc
> (https://pandoc.org/).
>
> One of the reasons to choose any wiki-like language (AsciiDoc, Markdown,
> etc) is you can use any text editor at all. I use a nice AsciiDoc plugin
> for IntelliJ IDEA. Your tastes may vary.
>
> Cheers
>
> Paul Foxworthy
>
> Hi Paul,

Do you know if there are there good reasons to favor Asciidoctor over
Pandoc?
I'm more in favour of the later because now I know it (thanks to you :))
and especially because it offers so much possibilities, see graph here
https://pandoc.org/
You never know what you will need one day...

Jacques

[Jacques Le Roux]

Ha thanks Taher, this answer to Michael's question: we indeed need Asciidoctor if we want to transform from Asciidoc to other formats. Then Pandoc can
possibly be used for more possibilities

Jacques


Le 08/11/2017 à 10:33, Taher Alkhateeb a écrit :

> If you check the link you sent, you will notice that asciidoc is not an
> input format in pandoc, but rather an ouput format.
>
> On Nov 8, 2017 12:29 PM, "Jacques Le Roux" <[hidden email]>
> wrote:
>
> Le 08/11/2017 à 08:25, Paul Foxworthy a écrit :
>
>> On 17 October 2017 at 20:25, Michael Brohl <[hidden email]>
>> wrote:
>>
>>
>> I assume that we can use any Asciidoc editor and need not to use
>>> Asciidoctor?
>>>
>>> Hi Michael,
>> Asciidoctor is not an editor, it's a text processor that can convert
>> AsciiDoc to HTML or DocBook XML. So it's an alternative processor to Pandoc
>> (https://pandoc.org/).
>>
>> One of the reasons to choose any wiki-like language (AsciiDoc, Markdown,
>> etc) is you can use any text editor at all. I use a nice AsciiDoc plugin
>> for IntelliJ IDEA. Your tastes may vary.
>>
>> Cheers
>>
>> Paul Foxworthy
>>
>> Hi Paul,
> Do you know if there are there good reasons to favor Asciidoctor over
> Pandoc?
> I'm more in favour of the later because now I know it (thanks to you :))
> and especially because it offers so much possibilities, see graph here
> https://pandoc.org/
> You never know what you will need one day...
>
> Jacques
>

[Sharan-F]

Hi All

At the Open Source Summit in Prague a couple of weeks ago I attended
quite a few documentation related talks and also interviewed one of the
presenters (Robert Kratky from Red Hat) for FeatherCast. He did a talk
about converting legacy docs into more user story based content, so bit
like what we need to do. Anyway his recommendation was Asciidoc and he
also had some links to resources that could help in our documentation
journey.

If the tool selection is actually stopping us from moving onto the next
step then let's present the proposal options (e.g Asciidoc, Pandoc etc)
and ask the community to select their preference..

Thanks
Sharan


On 08/11/17 10:33, Taher Alkhateeb wrote:

> If you check the link you sent, you will notice that asciidoc is not an
> input format in pandoc, but rather an ouput format.
>
> On Nov 8, 2017 12:29 PM, "Jacques Le Roux" <[hidden email]>
> wrote:
>
> Le 08/11/2017 à 08:25, Paul Foxworthy a écrit :
>
>> On 17 October 2017 at 20:25, Michael Brohl <[hidden email]>
>> wrote:
>>
>>
>> I assume that we can use any Asciidoc editor and need not to use
>>> Asciidoctor?
>>>
>>> Hi Michael,
>> Asciidoctor is not an editor, it's a text processor that can convert
>> AsciiDoc to HTML or DocBook XML. So it's an alternative processor to Pandoc
>> (https://pandoc.org/).
>>
>> One of the reasons to choose any wiki-like language (AsciiDoc, Markdown,
>> etc) is you can use any text editor at all. I use a nice AsciiDoc plugin
>> for IntelliJ IDEA. Your tastes may vary.
>>
>> Cheers
>>
>> Paul Foxworthy
>>
>> Hi Paul,
> Do you know if there are there good reasons to favor Asciidoctor over
> Pandoc?
> I'm more in favour of the later because now I know it (thanks to you :))
> and especially because it offers so much possibilities, see graph here
> https://pandoc.org/
> You never know what you will need one day...
>
> Jacques
>

[taher]

Hi Sharan,

As I was explaining to Jacques, there is no tool selection issue. Pandoc
cannot handle asciidoc and therefore the best viable choice is asciidoctor.
What is stopping us right now is my delay in implementing the feature ( I
am about half way through in OFBIZ-9873 to tackle the PoC ).

On Nov 8, 2017 1:21 PM, "Sharan Foga" <[hidden email]> wrote:

Hi All

At the Open Source Summit in Prague a couple of weeks ago I attended quite
a few documentation related talks and also interviewed one of the
presenters (Robert Kratky from Red Hat) for FeatherCast. He did a talk
about converting legacy docs into more user story based content, so bit
like what we need to do. Anyway his recommendation was Asciidoc and he also
had some links to resources that could help in our documentation journey.

If the tool selection is actually stopping us from moving onto the next
step then let's present the proposal options (e.g Asciidoc, Pandoc etc) and
ask the community to select their preference..

Thanks
Sharan



On 08/11/17 10:33, Taher Alkhateeb wrote:

> If you check the link you sent, you will notice that asciidoc is not an
> input format in pandoc, but rather an ouput format.
>
> On Nov 8, 2017 12:29 PM, "Jacques Le Roux" <[hidden email]>
> wrote:
>
> Le 08/11/2017 à 08:25, Paul Foxworthy a écrit :
>
> On 17 October 2017 at 20:25, Michael Brohl <[hidden email]>
>> wrote:
>>
>>
>> I assume that we can use any Asciidoc editor and need not to use
>>
>>> Asciidoctor?
>>>
>>> Hi Michael,
>>>
>> Asciidoctor is not an editor, it's a text processor that can convert
>> AsciiDoc to HTML or DocBook XML. So it's an alternative processor to
>> Pandoc
>> (https://pandoc.org/).
>>
>> One of the reasons to choose any wiki-like language (AsciiDoc, Markdown,
>> etc) is you can use any text editor at all. I use a nice AsciiDoc plugin
>> for IntelliJ IDEA. Your tastes may vary.
>>
>> Cheers
>>
>> Paul Foxworthy
>>
>> Hi Paul,
>>
> Do you know if there are there good reasons to favor Asciidoctor over
> Pandoc?
> I'm more in favour of the later because now I know it (thanks to you :))
> and especially because it offers so much possibilities, see graph here
> https://pandoc.org/
> You never know what you will need one day...
>
> Jacques
>
>

[Paul Foxworthy]

On 8 November 2017 at 20:33, Taher Alkhateeb <[hidden email]>
 wrote:

> If you check the link you sent, you will notice that asciidoc is not an
> input format in pandoc, but rather an ouput format.
>

Thanks Taher,

My impression was pandoc can read just about any structured input. It's
curious AsciiDoc isn't there.

So for HTML it's

AsciiDoc -- (asciidoctor) --> HTML

and for PDF it's

AsciiDoc -- (asciidoctor) --> DocBook XML -- (pandoc) --> PDF

That sound right?

Cheers

Paul

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

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

[taher]

Hi Paul,

First regarding your comment about pandoc, essentially pandoc is a set of
readers and writers. Each markup language needs a reader to convert from
and a writer to convert to. Asciidoc is missing a reader implementation. I
hope someone would implement it eventually.

Anyway I don't see a reason so far to use pandoc to publish to pdf.
Asciidoctor can publish to html, docbook, pdf and others. I like pandoc, it
is a swiss army knife kind of tool for conversion and written in haskell
(fantastic). However like a swiss army knife, it is not specialized like a
native tool designed for the job. So the time to use pandoc might be if
we're stuck or have some limitation with asciidoctor.

On Nov 9, 2017 2:28 AM, "Paul Foxworthy" <[hidden email]> wrote:

On 8 November 2017 at 20:33, Taher Alkhateeb <[hidden email]>
 wrote:

> If you check the link you sent, you will notice that asciidoc is not an
> input format in pandoc, but rather an ouput format.
>

Thanks Taher,

My impression was pandoc can read just about any structured input. It's
curious AsciiDoc isn't there.

So for HTML it's

AsciiDoc -- (asciidoctor) --> HTML

and for PDF it's

AsciiDoc -- (asciidoctor) --> DocBook XML -- (pandoc) --> PDF

That sound right?

Cheers

Paul

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

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

[Paul Foxworthy]

On 9 November 2017 at 18:26, Taher Alkhateeb <[hidden email]>
wrote:


> Anyway I don't see a reason so far to use pandoc to publish to pdf.
> Asciidoctor can publish to html, docbook, pdf and others.


Thanks Taher. That's fine by me.

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]

[taher]

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]

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
>

[Gil Portenseigne]

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

[taher]

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