Impersonation and Documentation

[Gil Portenseigne]

Hello,

I just published a new version of impersonation feature (OFBIZ-10515),
and i wrote down some asciidoc documentation.

I got some questions to documentation team to get the best practice
around it.

I write down a documentation within:
framework/security/src/doc/asciidoc/_include/security-impersonation.adoc
but i'm not sure about the location, since the gradle doc tasks do not
take it into account. I guess i'm wrong. If you can point me where is
the best place for this kind of documentation.

On another hand, i wanted to reference an icon within common-theme, i
set the property :
:imagesdir: ../../../../../../themes/common-theme/webapp/images/img/

Which is in my opinion a bad choice. I guess it's better to duplicate
the image within the documentation tree.

Thanks and regards,

Gil

[taher]

The asciidoc design is really simple: you have two main documents in
the system found under docs/asciidoc. One is the user manual and the
other one is the developer manual.

Each one of these documents is in turn, pointing to other documents
that by default are placed in /src/docs/asciidoc in each component and
holds the same component name. So if you want to add this
documentation, you will:
- Add an "include" section in the main documentation document
- Create your document in src/docs/asciidoc
- Provide the contents
- Test using ./gradlew generateOfbizDocumentation
On Fri, Sep 7, 2018 at 5:20 PM Gil Portenseigne
<[hidden email]> wrote:

>
> Hello,
>
> I just published a new version of impersonation feature (OFBIZ-10515),
> and i wrote down some asciidoc documentation.
>
> I got some questions to documentation team to get the best practice
> around it.
>
> I write down a documentation within:
> framework/security/src/doc/asciidoc/_include/security-impersonation.adoc
> but i'm not sure about the location, since the gradle doc tasks do not
> take it into account. I guess i'm wrong. If you can point me where is
> the best place for this kind of documentation.
>
> On another hand, i wanted to reference an icon within common-theme, i
> set the property :
> :imagesdir: ../../../../../../themes/common-theme/webapp/images/img/
>
> Which is in my opinion a bad choice. I guess it's better to duplicate
> the image within the documentation tree.
>
> Thanks and regards,
>
> Gil

[Jacques Le Roux]

Le 07/09/2018 à 16:19, Gil Portenseigne a écrit :
> On another hand, i wanted to reference an icon within common-theme, i
> set the property :
> :imagesdir: ../../../../../../themes/common-theme/webapp/images/img/
>
> Which is in my opinion a bad choice. I guess it's better to duplicate
> the image within the documentation tree.
Hi Gil,

To enlighten myself, why do you consider it a bad choice?

Jacques

[Jacques Le Roux]

Thanks Taher,

This is quite helpful. I'll just add that it generates 2 files in build:

build/asciidoc/ofbiz/html5/user-manual.html

build/asciidoc/ofbiz/html5/developer-manual.html

Jacques


Le 08/09/2018 à 18:46, Taher Alkhateeb a écrit :

> The asciidoc design is really simple: you have two main documents in
> the system found under docs/asciidoc. One is the user manual and the
> other one is the developer manual.
>
> Each one of these documents is in turn, pointing to other documents
> that by default are placed in /src/docs/asciidoc in each component and
> holds the same component name. So if you want to add this
> documentation, you will:
> - Add an "include" section in the main documentation document
> - Create your document in src/docs/asciidoc
> - Provide the contents
> - Test using ./gradlew generateOfbizDocumentation
> On Fri, Sep 7, 2018 at 5:20 PM Gil Portenseigne
> <[hidden email]> wrote:
>> Hello,
>>
>> I just published a new version of impersonation feature (OFBIZ-10515),
>> and i wrote down some asciidoc documentation.
>>
>> I got some questions to documentation team to get the best practice
>> around it.
>>
>> I write down a documentation within:
>> framework/security/src/doc/asciidoc/_include/security-impersonation.adoc
>> but i'm not sure about the location, since the gradle doc tasks do not
>> take it into account. I guess i'm wrong. If you can point me where is
>> the best place for this kind of documentation.
>>
>> On another hand, i wanted to reference an icon within common-theme, i
>> set the property :
>> :imagesdir: ../../../../../../themes/common-theme/webapp/images/img/
>>
>> Which is in my opinion a bad choice. I guess it's better to duplicate
>> the image within the documentation tree.
>>
>> Thanks and regards,
>>
>> Gil

[Gil Portenseigne]

Thanks Taher it's clear now :)

Regards

Gil


Le samedi 08 sept. 2018 à 19:46:17 (+0300), Taher Alkhateeb a écrit :

> The asciidoc design is really simple: you have two main documents in
> the system found under docs/asciidoc. One is the user manual and the
> other one is the developer manual.
>
> Each one of these documents is in turn, pointing to other documents
> that by default are placed in /src/docs/asciidoc in each component and
> holds the same component name. So if you want to add this
> documentation, you will:
> - Add an "include" section in the main documentation document
> - Create your document in src/docs/asciidoc
> - Provide the contents
> - Test using ./gradlew generateOfbizDocumentation
> On Fri, Sep 7, 2018 at 5:20 PM Gil Portenseigne
> <[hidden email]> wrote:
> >
> > Hello,
> >
> > I just published a new version of impersonation feature (OFBIZ-10515),
> > and i wrote down some asciidoc documentation.
> >
> > I got some questions to documentation team to get the best practice
> > around it.
> >
> > I write down a documentation within:
> > framework/security/src/doc/asciidoc/_include/security-impersonation.adoc
> > but i'm not sure about the location, since the gradle doc tasks do not
> > take it into account. I guess i'm wrong. If you can point me where is
> > the best place for this kind of documentation.
> >
> > On another hand, i wanted to reference an icon within common-theme, i
> > set the property :
> > :imagesdir: ../../../../../../themes/common-theme/webapp/images/img/
> >
> > Which is in my opinion a bad choice. I guess it's better to duplicate
> > the image within the documentation tree.
> >
> > Thanks and regards,
> >
> > Gil

[Gil Portenseigne]

Hello Jacques !

Anytime I see "../../../ ...", i feel like it's a bad design.

Moreover i think that documentation should be auto-sufficient, and should not be
code dependant. So a direct reference to theme material in this way
should be avoided.

Gil


Le lundi 10 sept. 2018 à 08:14:14 (+0200), Jacques Le Roux a écrit :

> Le 07/09/2018 à 16:19, Gil Portenseigne a écrit :
> > On another hand, i wanted to reference an icon within common-theme, i
> > set the property :
> > :imagesdir: ../../../../../../themes/common-theme/webapp/images/img/
> >
> > Which is in my opinion a bad choice. I guess it's better to duplicate
> > the image within the documentation tree.
> Hi Gil,
>
> To enlighten myself, why do you consider it a bad choice?
>
> Jacques
>

[taher]

perhaps you can place a copy of whatever you want in
$OFBIZ_HOME/docs/asciidoc/images/
On Mon, Sep 10, 2018 at 10:22 AM Gil Portenseigne
<[hidden email]> wrote:

>
> Hello Jacques !
>
> Anytime I see "../../../ ...", i feel like it's a bad design.
>
> Moreover i think that documentation should be auto-sufficient, and should not be
> code dependant. So a direct reference to theme material in this way
> should be avoided.
>
> Gil
>
>
> Le lundi 10 sept. 2018 à 08:14:14 (+0200), Jacques Le Roux a écrit :
> > Le 07/09/2018 à 16:19, Gil Portenseigne a écrit :
> > > On another hand, i wanted to reference an icon within common-theme, i
> > > set the property :
> > > :imagesdir: ../../../../../../themes/common-theme/webapp/images/img/
> > >
> > > Which is in my opinion a bad choice. I guess it's better to duplicate
> > > the image within the documentation tree.
> > Hi Gil,
> >
> > To enlighten myself, why do you consider it a bad choice?
> >
> > Jacques
> >

[Gil Portenseigne]

Yes that was my intention :), i should have said it so !

Le lundi 10 sept. 2018 à 10:28:24 (+0300), Taher Alkhateeb a écrit :

> perhaps you can place a copy of whatever you want in
> $OFBIZ_HOME/docs/asciidoc/images/
> On Mon, Sep 10, 2018 at 10:22 AM Gil Portenseigne
> <[hidden email]> wrote:
> >
> > Hello Jacques !
> >
> > Anytime I see "../../../ ...", i feel like it's a bad design.
> >
> > Moreover i think that documentation should be auto-sufficient, and should not be
> > code dependant. So a direct reference to theme material in this way
> > should be avoided.
> >
> > Gil
> >
> >
> > Le lundi 10 sept. 2018 à 08:14:14 (+0200), Jacques Le Roux a écrit :
> > > Le 07/09/2018 à 16:19, Gil Portenseigne a écrit :
> > > > On another hand, i wanted to reference an icon within common-theme, i
> > > > set the property :
> > > > :imagesdir: ../../../../../../themes/common-theme/webapp/images/img/
> > > >
> > > > Which is in my opinion a bad choice. I guess it's better to duplicate
> > > > the image within the documentation tree.
> > > Hi Gil,
> > >
> > > To enlighten myself, why do you consider it a bad choice?
> > >
> > > Jacques
> > >

[Jacques Le Roux]

Makes sense, thanks guys,

Redundancy is indeed not always bad. But you will have to maintain the consistency between the images, maybe a tool could be built and used?

Jacques


Le 10/09/2018 à 09:39, Gil Portenseigne a écrit :

> Yes that was my intention :), i should have said it so !
>
> Le lundi 10 sept. 2018 à 10:28:24 (+0300), Taher Alkhateeb a écrit :
>> perhaps you can place a copy of whatever you want in
>> $OFBIZ_HOME/docs/asciidoc/images/
>> On Mon, Sep 10, 2018 at 10:22 AM Gil Portenseigne
>> <[hidden email]> wrote:
>>> Hello Jacques !
>>>
>>> Anytime I see "../../../ ...", i feel like it's a bad design.
>>>
>>> Moreover i think that documentation should be auto-sufficient, and should not be
>>> code dependant. So a direct reference to theme material in this way
>>> should be avoided.
>>>
>>> Gil
>>>
>>>
>>> Le lundi 10 sept. 2018 à 08:14:14 (+0200), Jacques Le Roux a écrit :
>>>> Le 07/09/2018 à 16:19, Gil Portenseigne a écrit :
>>>>> On another hand, i wanted to reference an icon within common-theme, i
>>>>> set the property :
>>>>> :imagesdir: ../../../../../../themes/common-theme/webapp/images/img/
>>>>>
>>>>> Which is in my opinion a bad choice. I guess it's better to duplicate
>>>>> the image within the documentation tree.
>>>> Hi Gil,
>>>>
>>>> To enlighten myself, why do you consider it a bad choice?
>>>>
>>>> Jacques
>>>>

[Gil Portenseigne]

A tool for this purpose is in my opinion do not fit, we need
to commit ourselves to doc maintainment, when the code base is changed.
I do not see any good working automation around that, this has to be
done manually to ensure a good documenation.

Gil



Le lundi 10 sept. 2018 à 11:00:11 (+0200), Jacques Le Roux a écrit :

> Makes sense, thanks guys,
>
> Redundancy is indeed not always bad. But you will have to maintain the consistency between the images, maybe a tool could be built and used?
>
> Jacques
>
>
> Le 10/09/2018 à 09:39, Gil Portenseigne a écrit :
> > Yes that was my intention :), i should have said it so !
> >
> > Le lundi 10 sept. 2018 à 10:28:24 (+0300), Taher Alkhateeb a écrit :
> > > perhaps you can place a copy of whatever you want in
> > > $OFBIZ_HOME/docs/asciidoc/images/
> > > On Mon, Sep 10, 2018 at 10:22 AM Gil Portenseigne
> > > <[hidden email]> wrote:
> > > > Hello Jacques !
> > > >
> > > > Anytime I see "../../../ ...", i feel like it's a bad design.
> > > >
> > > > Moreover i think that documentation should be auto-sufficient, and should not be
> > > > code dependant. So a direct reference to theme material in this way
> > > > should be avoided.
> > > >
> > > > Gil
> > > >
> > > >
> > > > Le lundi 10 sept. 2018 à 08:14:14 (+0200), Jacques Le Roux a écrit :
> > > > > Le 07/09/2018 à 16:19, Gil Portenseigne a écrit :
> > > > > > On another hand, i wanted to reference an icon within common-theme, i
> > > > > > set the property :
> > > > > > :imagesdir: ../../../../../../themes/common-theme/webapp/images/img/
> > > > > >
> > > > > > Which is in my opinion a bad choice. I guess it's better to duplicate
> > > > > > the image within the documentation tree.
> > > > > Hi Gil,
> > > > >
> > > > > To enlighten myself, why do you consider it a bad choice?
> > > > >
> > > > > Jacques
> > > > >
>

[Mathieu Lirzin]

Hello,

Gil Portenseigne <[hidden email]> writes:

> A tool for this purpose is in my opinion do not fit, we need
> to commit ourselves to doc maintainment, when the code base is changed.
> I do not see any good working automation around that, this has to be
> done manually to ensure a good documenation.

Even if people try to be thorough, it is very likely that they will
eventually overlook that the documentation needs to be updated.

While I sympathize with any effort of avoiding the over-tooling trap, I
think it is *very* important to have consistency between the
documentation and the actual code in use for example ensuring that the
code examples provided in the documentation are still working.  Given
the complexity of OFBiz, it would be really harmful for newcomers if
that was not the case.  AIUI having a mismatch of images while not being
as damaging as a code example mismatch is still something that is
important to avoid.  As a consequence I would be in favour of some
tooling that helps in that regard.

I personnally don't mind the “../../..” thing if the documentation build
process fails when the providing file name is incorrect.  However if the
issue is about readability, maybe Asciidoc provides a way to define
variables?  If so, file name prefixes could be defined with a variable
with a meaningful name that could then be reused when referring to an
external file.

--
Mathieu Lirzin
GPG: F2A3 8D7E EB2B 6640 5761  070D 0ADE E100 9460 4D37

[taher]

Actually, Mathieu made a very good point. Asciidoc does indeed support
variables. I think that's the best middle solution.
On Mon, Sep 10, 2018 at 3:21 PM Mathieu Lirzin
<[hidden email]> wrote:

>
> Hello,
>
> Gil Portenseigne <[hidden email]> writes:
>
> > A tool for this purpose is in my opinion do not fit, we need
> > to commit ourselves to doc maintainment, when the code base is changed.
> > I do not see any good working automation around that, this has to be
> > done manually to ensure a good documenation.
>
> Even if people try to be thorough, it is very likely that they will
> eventually overlook that the documentation needs to be updated.
>
> While I sympathize with any effort of avoiding the over-tooling trap, I
> think it is *very* important to have consistency between the
> documentation and the actual code in use for example ensuring that the
> code examples provided in the documentation are still working.  Given
> the complexity of OFBiz, it would be really harmful for newcomers if
> that was not the case.  AIUI having a mismatch of images while not being
> as damaging as a code example mismatch is still something that is
> important to avoid.  As a consequence I would be in favour of some
> tooling that helps in that regard.
>
> I personnally don't mind the “../../..” thing if the documentation build
> process fails when the providing file name is incorrect.  However if the
> issue is about readability, maybe Asciidoc provides a way to define
> variables?  If so, file name prefixes could be defined with a variable
> with a meaningful name that could then be reused when referring to an
> external file.
>
> --
> Mathieu Lirzin
> GPG: F2A3 8D7E EB2B 6640 5761  070D 0ADE E100 9460 4D37