ofbiz-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Craig Parker <cr...@fossfolks.com>
Subject Re: [Discussion] documentation framework for OFBiz
Date Wed, 17 Jan 2018 15:56:26 GMT
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 <craig@fossfolks.com> 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"<sharan@apache.org> 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 <slidingfilaments@gmail.com> 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
>>>>> <slidingfilaments@gmail.com> 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
>>


Mime
View raw message