Plugins documentation and framework

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

Plugins documentation and framework

holivier
Hi Community,

I start migrate plugins docbook for ofbiz-plugins and I have a question about
How to manage plugins documentation, in the structure of user-documentation and developper-manual ?

I see 3 possible solutions
1) Current solution: one document per plugin, and link to its in the correct chapter
   example: plugins ldap, doc SingleSignOn : it is generated as
https://ci.apache.org/projects/ofbiz/site/trunk/pluginsdoc/ldap/html5/SingleSignOn.html
            in developper-manual, put a link to this doc in the Deployment chapter

2) add a "include::" in the correct chapter (created a dependency between framework and plugins)
   example: currently in Deployment chapter there is the "11.2. OFBiz Single Sign On using CAS and LDAP" as sub-chapter

3) add a "include::" to a doc/asciidoc/plugins-user-documentation in user-ddocumentation
          and one to doc/asciidoc/plugins-developper-manual in developper-manual
   In each file there will be all the include to tha appropriate plugins.
Reply | Threaded
Open this post in threaded view
|

Re: Plugins documentation and framework

Olivier.heintz
My point of view about my question ;-)

On a Documentation, point of view, I prefer the solution 2, (with a clear flag to say it's a with the plugin xxxx)

On a technical point of view to have minimum dependency between framework and plugins, solution 3 is the better one

Le 15/07/2020 à 10:53, Olivier Heintz a écrit :

> Hi Community,
>
> I start migrate plugins docbook for ofbiz-plugins and I have a question about
> How to manage plugins documentation, in the structure of user-documentation and developper-manual ?
>
> I see 3 possible solutions
> 1) Current solution: one document per plugin, and link to its in the correct chapter
>    example: plugins ldap, doc SingleSignOn : it is generated as
> https://ci.apache.org/projects/ofbiz/site/trunk/pluginsdoc/ldap/html5/SingleSignOn.html
>             in developper-manual, put a link to this doc in the Deployment chapter
>
> 2) add a "include::" in the correct chapter (created a dependency between framework and plugins)
>    example: currently in Deployment chapter there is the "11.2. OFBiz Single Sign On using CAS and LDAP" as sub-chapter
>
> 3) add a "include::" to a doc/asciidoc/plugins-user-documentation in user-ddocumentation
>           and one to doc/asciidoc/plugins-developper-manual in developper-manual
>    In each file there will be all the include to tha appropriate plugins.
>
Reply | Threaded
Open this post in threaded view
|

Re: Plugins documentation and framework

Jacques Le Roux
Administrator
Hi Olivier,

First I must thank all your work on documentation and this proposition

With documentation maintenance in mind, I think it's best to clearly split between framework and plugins, so solution 3 seems better to me.

Jacques

Le 15/07/2020 à 11:00, Olivier Heintz a écrit :

> My point of view about my question ;-)
>
> On a Documentation, point of view, I prefer the solution 2, (with a clear flag to say it's a with the plugin xxxx)
>
> On a technical point of view to have minimum dependency between framework and plugins, solution 3 is the better one
>
> Le 15/07/2020 à 10:53, Olivier Heintz a écrit :
>> Hi Community,
>>
>> I start migrate plugins docbook for ofbiz-plugins and I have a question about
>> How to manage plugins documentation, in the structure of user-documentation and developper-manual ?
>>
>> I see 3 possible solutions
>> 1) Current solution: one document per plugin, and link to its in the correct chapter
>>     example: plugins ldap, doc SingleSignOn : it is generated as
>> https://ci.apache.org/projects/ofbiz/site/trunk/pluginsdoc/ldap/html5/SingleSignOn.html
>>              in developper-manual, put a link to this doc in the Deployment chapter
>>
>> 2) add a "include::" in the correct chapter (created a dependency between framework and plugins)
>>     example: currently in Deployment chapter there is the "11.2. OFBiz Single Sign On using CAS and LDAP" as sub-chapter
>>
>> 3) add a "include::" to a doc/asciidoc/plugins-user-documentation in user-ddocumentation
>>            and one to doc/asciidoc/plugins-developper-manual in developper-manual
>>     In each file there will be all the include to tha appropriate plugins.
>>