[DISCUSSION] OFBiz Online Documentation

[Sharan-F]

I'd like to put forward a proposal for discussion around the project End User Documentation.

We know that we have incomplete documentation and need an active strategy to complete it. The help itself can be divided it into two distinct areas

1. Online / in Application Help
2. User Documentation on the Wiki (NOTE: I will be starting another discussion thread around this)


Online / In Application Help
This is the help that appears when someone using OFBiz clicks the help icon. It is contextual and normally related to a screen that the user is on. It can describe what a screen is used for, the data to be entered or the use of a key, button or icon.

Screens and menus can be changed so it needs to be flexible and customisable.

Our current online help has been implemented using Docbook and the OFBiz CMS. I don't think that this currently works well because

- it is too hard to keep up to date as each change needs to be submitted as a patch
- you need to understand and create the new data items for the CMS for each page of documentation
- existing items need to be linked into the correct place in the document hierarchy
- the docbook implementation isn't complete and there are a lot standard tags that cannot be used

Proposal
We know that we have had limited contributions to the online help system and currently this has been significantly reduced.

If we could make the online help more accessible to our community to update this could stimulate more interest in it.

Rather than trying to maintain the online help as if it were code – could it be treated differently to allow a wider range of people to provide updates.

As an example, I would like to find out if all the data from the online help :

- could be extracted
- imported into a more document oriented/friendly editing environment or application
- updated by community members (who could be given access to create / update / edit details)
- changes would be reviewed and approved
- once approved the changes could be committed / the help could be re-imported back into OFBiz or just delivered as a separate package that could be easily loaded back into OFBiz

Potential Benefits
- Community Members could work and update it easily
- Reviews could be done before the documents are accepted
- Different languages could be supported
- We could have versions of help for different OFBiz versions

These are my initial thoughts so I'm happy to get any feedback or alternative suggestions for how we could solve our existing problems.

Thanks
Sharan

[Todd Thorner]

I'm willing to pitch in, but as I stated in a message earlier today I'm
still rather ignorant about OFBiz (I've had zero free time to take the
figurative plunge).

First and foremost for documentation: single-sourcing and DITA/DocBook.
 Discuss ...



On 15-05-21 09:45 AM, Sharan-F wrote:

> I'd like to put forward a proposal for discussion around the project End User
> Documentation.
>
> We know that we have incomplete documentation and need an active strategy to
> complete it. The help itself can be divided it into two distinct areas
>
> 1. Online / in Application Help
> 2. User Documentation on the Wiki (NOTE: I will be starting another
> discussion thread around this)
>
> *
> Online / In Application Help*
> This is the help that appears when someone using OFBiz clicks the help icon.
> It is contextual and normally related to a screen that the user is on. It
> can describe what a screen is used for, the data to be entered or the use of
> a key, button or icon.
>
> Screens and menus can be changed so it needs to be flexible and
> customisable.
>
> Our current online help has been implemented using Docbook and the OFBiz
> CMS. I don't think that this currently works well because
>
> - it is too hard to keep up to date as each change needs to be submitted as
> a patch
> - you need to understand and create the new data items for the CMS for each
> page of documentation
> - existing items need to be linked into the correct place in the document
> hierarchy
> - the docbook implementation isn't complete and there are a lot standard
> tags that cannot be used
>
> *Proposal*
> We know that we have had limited contributions to the online help system and
> currently this has been significantly reduced.
>
> If we could make the online help more accessible to our community to update
> this could stimulate more interest in it.
>
> Rather than trying to maintain the online help as if it were code – could it
> be treated differently to allow a wider range of people to provide updates.
>
> As an example, I would like to find out if all the data from the online help
> :
>
> - could be extracted
> - imported into a more document oriented/friendly editing environment or
> application
> - updated by community members (who could be given access to create / update
> / edit details)
> - changes would be reviewed and approved
> - once approved the changes could be committed / the help could be
> re-imported back into OFBiz or just delivered as a separate package that
> could be easily loaded back into OFBiz
>
> *Potential Benefits*
> - Community Members could work and update it easily
> - Reviews could be done before the documents are accepted
> - Different languages could be supported
> - We could have versions of help for different OFBiz versions
>
> These are my initial thoughts so I'm happy to get any feedback or
> alternative suggestions for how we could solve our existing problems.
>
> Thanks
> Sharan
>
>
>
> --
> View this message in context: http://ofbiz.135035.n4.nabble.com/DISCUSSION-OFBiz-Online-Documentation-tp4668869.html
> Sent from the OFBiz - User mailing list archive at Nabble.com.
>

[Sharan-F]

Hi All

I'm still looking for some community feedback on this proposal and approach and now I have a couple of extra questions.

To any OFBiz Service providers out there – how do you manage the online help when you install or implement OFBiz? (Is it left as it is, do you remove it or do you create some new online help?)

To the general community at large - what is the overall feeling about extracting the online help, updating it and then packaging it as a separate project deliverable that can be easily integrated back into OFBiz?

I'm focussing on the approach first. I think that once we have had the discussion about that and reach a concensus can we start discussions around the technology and options to achieve it.

Thanks
Sharan

[marcopaul]

End user here - online help has always been a weak spot for OFbiz.

I would suggest putting more effort into making things self-documenting whenever possible. For example, adding descriptive tool tips to what buttons do ("clicking this will process the order and notify the customer") and more action-oriented names for things. Apple has great UI guidelines for making these kinds of things self documenting.


--Paul (From Mobile)

> On May 27, 2015, at 8:34 AM, Sharan-F <[hidden email]> wrote:
>
> Hi All
>
> I'm still looking for some community feedback on this proposal and approach
> and now I have a couple of extra questions.
>
> To any OFBiz Service providers out there – how do you manage the online help
> when you install or implement OFBiz? (Is it left as it is, do you remove it
> or do you create some new online help?)
>
> To the general community at large - what is the overall feeling about
> extracting the online help, updating it and then packaging it as a separate
> project deliverable that can be easily integrated back into OFBiz?
>
> I'm focussing on the approach first. I think that once we have had the
> discussion about that and reach a concensus can we start discussions around
> the technology and options to achieve it.
>
> Thanks
> Sharan
>
>
>
> --
> View this message in context: http://ofbiz.135035.n4.nabble.com/DISCUSSION-OFBiz-Online-Documentation-tp4668869p4669054.html
> Sent from the OFBiz - User mailing list archive at Nabble.com.

[Michael Brohl-3]

Hi Sharan,

I had not the time to think more about your proposal but I can quickly
answer your followup questions, see inline...

Am 27.05.15 um 15:34 schrieb Sharan-F:
> Hi All
>
> I'm still looking for some community feedback on this proposal and approach
> and now I have a couple of extra questions.
>
> To any OFBiz Service providers out there – how do you manage the online help
> when you install or implement OFBiz? (Is it left as it is, do you remove it
> or do you create some new online help?)
In most of our projects, the existing online help is not used at all.
The nature of our projects are mostly eCommerce and portal systems with
another ERP backend like SAP. So the OFBiz backend is either not used at
all or only a small part is used. We do trainings with the end users
then and sometimes write some kind of manual which describes the backend
use in context to the customer specific processes.

I think there was only one project in the past 13 years which used the
online help with partly modified texts.
>
> To the general community at large - what is the overall feeling about
> extracting the online help, updating it and then packaging it as a separate
> project deliverable that can be easily integrated back into OFBiz?
Mmmhh, we have to make sure that the contents of the online help are in
sync with the development and that it is easily editable for project
specific changes. Then I'm fine with it.
>
> I'm focussing on the approach first. I think that once we have had the
> discussion about that and reach a concensus can we start discussions around
> the technology and options to achieve it.
>
> Thanks
> Sharan
>
Regards,

Michael Brohl
ecomify GmbH
www.ecomify.de

[Ron Wheeler]

On 27/05/2015 10:50 AM, Michael Brohl wrote:

> Hi Sharan,
>
> I had not the time to think more about your proposal but I can quickly
> answer your followup questions, see inline...
>
> Am 27.05.15 um 15:34 schrieb Sharan-F:
>> Hi All
>>
>> I'm still looking for some community feedback on this proposal and
>> approach
>> and now I have a couple of extra questions.
>>
>> To any OFBiz Service providers out there – how do you manage the
>> online help
>> when you install or implement OFBiz? (Is it left as it is, do you
>> remove it
>> or do you create some new online help?)
> In most of our projects, the existing online help is not used at all.
> The nature of our projects are mostly eCommerce and portal systems
> with another ERP backend like SAP. So the OFBiz backend is either not
> used at all or only a small part is used. We do trainings with the end
> users then and sometimes write some kind of manual which describes the
> backend use in context to the customer specific processes.
>
> I think there was only one project in the past 13 years which used the
> online help with partly modified texts.

This is where DITA would be a big help since you could customize the
topics that you need to change and leave the rest as is.
I do this with our ADTransform product wherein I write a DITAMAP for a
customer that pulls in common topics from the main manual library and
customized topics written for each customer where we are providing the
ETVL scripts and want to document the customers particular ETVL workflow.

This short article introduces a good methodology for handling language
customization.
http://www.technical-writer.org/technical-communication/dita-xml-open-toolkit-multilingual-documentation-projects-tutorial-script-linux-bash/
It probably overly detailed for this point in the discussion but I did
want to point out how a single overall map can be used to produce
manuals in different languages that are guaranteed to at least contain
the same topics.
It also shows how a multilingual manual would be set up as a project and
generated (it shows the linux command line not the IDE as I would
recommend) for those who like to get into the nuts and bolts early.


>>
>> To the general community at large - what is the overall feeling about
>> extracting the online help, updating it and then packaging it as a
>> separate
>> project deliverable that can be easily integrated back into OFBiz?
> Mmmhh, we have to make sure that the contents of the online help are
> in sync with the development and that it is easily editable for
> project specific changes. Then I'm fine with it.
For our ADTransform ETVL product which is a batch process(no on-line
help possible or needed) , I use DITA for the manual and edit it in my
IDE and store it as an SVN (I know that I am old fashioned!) project
with my code so I can edit the docs and code together in the IDE.
I produce the manual using Maven within the IDE.

This makes it easier to keep both in synch by changing whichever file is
wrong. Sometimes I write the manual topic first so I capture the spec
before coding it and sometimes I think of good ideas while coding that
changes the topic in the manual so it is nice to have both files open in
the IDE at the same time.

It does encourage me to write better specs since I have to think out and
explain in plain language what the new feature is going to do for the
user and clearly describe the meaning and possible ranges of values of
each of  the configuration parameters.

I also feel better knowing that the effort spent on writing a clear spec
will save (or eliminate) documentation effort later. Counters the WISCY
syndrome.

>>
>> I'm focussing on the approach first. I think that once we have had the
>> discussion about that and reach a concensus can we start discussions
>> around
>> the technology and options to achieve it.
>>
>> Thanks
>> Sharan
>>
> Regards,
>
> Michael Brohl
> ecomify GmbH
> www.ecomify.de
>

--
Ron Wheeler
President
Artifact Software Inc
email: [hidden email]
skype: ronaldmwheeler
phone: [phone], ext 102

[Jacques Le Roux]

Le 27/05/2015 16:41, Paul Mandeltort a écrit :
> End user here - online help has always been a weak spot for OFbiz.
>
> I would suggest putting more effort into making things self-documenting whenever possible. For example, adding descriptive tool tips to what buttons do ("clicking this will process the order and notify the customer") and more action-oriented names for things. Apple has great UI guidelines for making these kinds of things self documenting.

Due to the nature of the projects we (integrators, service providers) support (as eg well explained Michael) that sounds like a great suggestion to
me. Would you have a link to "Apple has great UI guidelines"?

Thanks

Jacques

>
>
> --Paul (From Mobile)
>
>> On May 27, 2015, at 8:34 AM, Sharan-F <[hidden email]> wrote:
>>
>> Hi All
>>
>> I'm still looking for some community feedback on this proposal and approach
>> and now I have a couple of extra questions.
>>
>> To any OFBiz Service providers out there – how do you manage the online help
>> when you install or implement OFBiz? (Is it left as it is, do you remove it
>> or do you create some new online help?)
>>
>> To the general community at large - what is the overall feeling about
>> extracting the online help, updating it and then packaging it as a separate
>> project deliverable that can be easily integrated back into OFBiz?
>>
>> I'm focussing on the approach first. I think that once we have had the
>> discussion about that and reach a concensus can we start discussions around
>> the technology and options to achieve it.
>>
>> Thanks
>> Sharan
>>
>>
>>
>> --
>> View this message in context: http://ofbiz.135035.n4.nabble.com/DISCUSSION-OFBiz-Online-Documentation-tp4668869p4669054.html
>> Sent from the OFBiz - User mailing list archive at Nabble.com.
>

[Jacques Le Roux]

That sounds quite an interesting way Ron.
I also believe we should get rid of DocBook in favour of DITTA or maybe even AsciiDoc (the last smart guy) as we already discussed at the bottom of
https://issues.apache.org/jira/browse/OFBIZ-4941
I also like the idea of separating the documentation from the project (Yippee our 1st sub-project Ron ;) ).
Finally, like I said in OFBIZ-4941 I HATE CONFLUENCE, but also, like outlined Sharan (damn can't find the link again), it has a lot of features,
notably when it comes to transform formats... and anyway it's our wiki support...

Jacques

Le 27/05/2015 17:55, Ron Wheeler a écrit :

> On 27/05/2015 10:50 AM, Michael Brohl wrote:
>> Hi Sharan,
>>
>> I had not the time to think more about your proposal but I can quickly answer your followup questions, see inline...
>>
>> Am 27.05.15 um 15:34 schrieb Sharan-F:
>>> Hi All
>>>
>>> I'm still looking for some community feedback on this proposal and approach
>>> and now I have a couple of extra questions.
>>>
>>> To any OFBiz Service providers out there – how do you manage the online help
>>> when you install or implement OFBiz? (Is it left as it is, do you remove it
>>> or do you create some new online help?)
>> In most of our projects, the existing online help is not used at all. The nature of our projects are mostly eCommerce and portal systems with
>> another ERP backend like SAP. So the OFBiz backend is either not used at all or only a small part is used. We do trainings with the end users then
>> and sometimes write some kind of manual which describes the backend use in context to the customer specific processes.
>>
>> I think there was only one project in the past 13 years which used the online help with partly modified texts.
> This is where DITA would be a big help since you could customize the topics that you need to change and leave the rest as is.
> I do this with our ADTransform product wherein I write a DITAMAP for a customer that pulls in common topics from the main manual library and
> customized topics written for each customer where we are providing the ETVL scripts and want to document the customers particular ETVL workflow.
>
> This short article introduces a good methodology for handling language customization.
> http://www.technical-writer.org/technical-communication/dita-xml-open-toolkit-multilingual-documentation-projects-tutorial-script-linux-bash/
> It probably overly detailed for this point in the discussion but I did want to point out how a single overall map can be used to produce manuals in
> different languages that are guaranteed to at least contain the same topics.
> It also shows how a multilingual manual would be set up as a project and generated (it shows the linux command line not the IDE as I would
> recommend) for those who like to get into the nuts and bolts early.
>
>
>>>
>>> To the general community at large - what is the overall feeling about
>>> extracting the online help, updating it and then packaging it as a separate
>>> project deliverable that can be easily integrated back into OFBiz?
>> Mmmhh, we have to make sure that the contents of the online help are in sync with the development and that it is easily editable for project
>> specific changes. Then I'm fine with it.
> For our ADTransform ETVL product which is a batch process(no on-line help possible or needed) , I use DITA for the manual and edit it in my IDE and
> store it as an SVN (I know that I am old fashioned!) project with my code so I can edit the docs and code together in the IDE.
> I produce the manual using Maven within the IDE.
>
> This makes it easier to keep both in synch by changing whichever file is wrong. Sometimes I write the manual topic first so I capture the spec
> before coding it and sometimes I think of good ideas while coding that changes the topic in the manual so it is nice to have both files open in the
> IDE at the same time.
>
> It does encourage me to write better specs since I have to think out and explain in plain language what the new feature is going to do for the user
> and clearly describe the meaning and possible ranges of values of each of  the configuration parameters.
>
> I also feel better knowing that the effort spent on writing a clear spec will save (or eliminate) documentation effort later. Counters the WISCY
> syndrome.
>
>>>
>>> I'm focussing on the approach first. I think that once we have had the
>>> discussion about that and reach a concensus can we start discussions around
>>> the technology and options to achieve it.
>>>
>>> Thanks
>>> Sharan
>>>
>> Regards,
>>
>> Michael Brohl
>> ecomify GmbH
>> www.ecomify.de
>>
>
>

[taher]

Hi Jacques and all,

If you want a simple documentation language then markdown comes to mind. It is simple, beautiful, mature and well supported in terms of tools and probably covers the 90% of cases needed by everyone. So throwing another suggestion in the mix.

Taher Alkhateeb

----- Original Message -----

From: "Jacques Le Roux" <[hidden email]>
To: [hidden email]
Sent: Thursday, 28 May, 2015 12:51:13 PM
Subject: Re: [DISCUSSION] OFBiz Online Documentation

That sounds quite an interesting way Ron.
I also believe we should get rid of DocBook in favour of DITTA or maybe even AsciiDoc (the last smart guy) as we already discussed at the bottom of
https://issues.apache.org/jira/browse/OFBIZ-4941 
I also like the idea of separating the documentation from the project (Yippee our 1st sub-project Ron ;) ).
Finally, like I said in OFBIZ-4941 I HATE CONFLUENCE, but also, like outlined Sharan (damn can't find the link again), it has a lot of features,
notably when it comes to transform formats... and anyway it's our wiki support...

Jacques

Le 27/05/2015 17:55, Ron Wheeler a écrit :

> On 27/05/2015 10:50 AM, Michael Brohl wrote:
>> Hi Sharan,
>>
>> I had not the time to think more about your proposal but I can quickly answer your followup questions, see inline...
>>
>> Am 27.05.15 um 15:34 schrieb Sharan-F:
>>> Hi All
>>>
>>> I'm still looking for some community feedback on this proposal and approach
>>> and now I have a couple of extra questions.
>>>
>>> To any OFBiz Service providers out there – how do you manage the online help
>>> when you install or implement OFBiz? (Is it left as it is, do you remove it
>>> or do you create some new online help?)
>> In most of our projects, the existing online help is not used at all. The nature of our projects are mostly eCommerce and portal systems with
>> another ERP backend like SAP. So the OFBiz backend is either not used at all or only a small part is used. We do trainings with the end users then
>> and sometimes write some kind of manual which describes the backend use in context to the customer specific processes.
>>
>> I think there was only one project in the past 13 years which used the online help with partly modified texts.
> This is where DITA would be a big help since you could customize the topics that you need to change and leave the rest as is.
> I do this with our ADTransform product wherein I write a DITAMAP for a customer that pulls in common topics from the main manual library and
> customized topics written for each customer where we are providing the ETVL scripts and want to document the customers particular ETVL workflow.
>
> This short article introduces a good methodology for handling language customization.
> http://www.technical-writer.org/technical-communication/dita-xml-open-toolkit-multilingual-documentation-projects-tutorial-script-linux-bash/ 
> It probably overly detailed for this point in the discussion but I did want to point out how a single overall map can be used to produce manuals in
> different languages that are guaranteed to at least contain the same topics.
> It also shows how a multilingual manual would be set up as a project and generated (it shows the linux command line not the IDE as I would
> recommend) for those who like to get into the nuts and bolts early.
>
>
>>>
>>> To the general community at large - what is the overall feeling about
>>> extracting the online help, updating it and then packaging it as a separate
>>> project deliverable that can be easily integrated back into OFBiz?
>> Mmmhh, we have to make sure that the contents of the online help are in sync with the development and that it is easily editable for project
>> specific changes. Then I'm fine with it.
> For our ADTransform ETVL product which is a batch process(no on-line help possible or needed) , I use DITA for the manual and edit it in my IDE and
> store it as an SVN (I know that I am old fashioned!) project with my code so I can edit the docs and code together in the IDE.
> I produce the manual using Maven within the IDE.
>
> This makes it easier to keep both in synch by changing whichever file is wrong. Sometimes I write the manual topic first so I capture the spec
> before coding it and sometimes I think of good ideas while coding that changes the topic in the manual so it is nice to have both files open in the
> IDE at the same time.
>
> It does encourage me to write better specs since I have to think out and explain in plain language what the new feature is going to do for the user
> and clearly describe the meaning and possible ranges of values of each of the configuration parameters.
>
> I also feel better knowing that the effort spent on writing a clear spec will save (or eliminate) documentation effort later. Counters the WISCY
> syndrome.
>
>>>
>>> I'm focussing on the approach first. I think that once we have had the
>>> discussion about that and reach a concensus can we start discussions around
>>> the technology and options to achieve it.
>>>
>>> Thanks
>>> Sharan
>>>
>> Regards,
>>
>> Michael Brohl
>> ecomify GmbH
>> www.ecomify.de
>>
>
>

[Jacques Le Roux]

I'm still undecided on this, but I feel AsciiDoc is "slowly" gaining interest see http://www.artima.com/forums/flat.jsp?forum=106&thread=361787 It's
the same spirit than Json againt XML...Though Markdown is not XML, but Dita is. Also AsciiDoc offers a lot of export possibilities, see
http://en.wikipedia.org/wiki/Comparison_of_document_markup_languages

Anyway we will need a community consensus...

Jacques

Le 28/05/2015 12:29, Taher Alkhateeb a écrit :

> Hi Jacques and all,
>
> If you want a simple documentation language then markdown comes to mind. It is simple, beautiful, mature and well supported in terms of tools and probably covers the 90% of cases needed by everyone. So throwing another suggestion in the mix.
>
> Taher Alkhateeb
>
> ----- Original Message -----
>
> From: "Jacques Le Roux" <[hidden email]>
> To: [hidden email]
> Sent: Thursday, 28 May, 2015 12:51:13 PM
> Subject: Re: [DISCUSSION] OFBiz Online Documentation
>
> That sounds quite an interesting way Ron.
> I also believe we should get rid of DocBook in favour of DITTA or maybe even AsciiDoc (the last smart guy) as we already discussed at the bottom of
> https://issues.apache.org/jira/browse/OFBIZ-4941
> I also like the idea of separating the documentation from the project (Yippee our 1st sub-project Ron ;) ).
> Finally, like I said in OFBIZ-4941 I HATE CONFLUENCE, but also, like outlined Sharan (damn can't find the link again), it has a lot of features,
> notably when it comes to transform formats... and anyway it's our wiki support...
>
> Jacques
>
> Le 27/05/2015 17:55, Ron Wheeler a écrit :
>> On 27/05/2015 10:50 AM, Michael Brohl wrote:
>>> Hi Sharan,
>>>
>>> I had not the time to think more about your proposal but I can quickly answer your followup questions, see inline...
>>>
>>> Am 27.05.15 um 15:34 schrieb Sharan-F:
>>>> Hi All
>>>>
>>>> I'm still looking for some community feedback on this proposal and approach
>>>> and now I have a couple of extra questions.
>>>>
>>>> To any OFBiz Service providers out there – how do you manage the online help
>>>> when you install or implement OFBiz? (Is it left as it is, do you remove it
>>>> or do you create some new online help?)
>>> In most of our projects, the existing online help is not used at all. The nature of our projects are mostly eCommerce and portal systems with
>>> another ERP backend like SAP. So the OFBiz backend is either not used at all or only a small part is used. We do trainings with the end users then
>>> and sometimes write some kind of manual which describes the backend use in context to the customer specific processes.
>>>
>>> I think there was only one project in the past 13 years which used the online help with partly modified texts.
>> This is where DITA would be a big help since you could customize the topics that you need to change and leave the rest as is.
>> I do this with our ADTransform product wherein I write a DITAMAP for a customer that pulls in common topics from the main manual library and
>> customized topics written for each customer where we are providing the ETVL scripts and want to document the customers particular ETVL workflow.
>>
>> This short article introduces a good methodology for handling language customization.
>> http://www.technical-writer.org/technical-communication/dita-xml-open-toolkit-multilingual-documentation-projects-tutorial-script-linux-bash/
>> It probably overly detailed for this point in the discussion but I did want to point out how a single overall map can be used to produce manuals in
>> different languages that are guaranteed to at least contain the same topics.
>> It also shows how a multilingual manual would be set up as a project and generated (it shows the linux command line not the IDE as I would
>> recommend) for those who like to get into the nuts and bolts early.
>>
>>
>>>> To the general community at large - what is the overall feeling about
>>>> extracting the online help, updating it and then packaging it as a separate
>>>> project deliverable that can be easily integrated back into OFBiz?
>>> Mmmhh, we have to make sure that the contents of the online help are in sync with the development and that it is easily editable for project
>>> specific changes. Then I'm fine with it.
>> For our ADTransform ETVL product which is a batch process(no on-line help possible or needed) , I use DITA for the manual and edit it in my IDE and
>> store it as an SVN (I know that I am old fashioned!) project with my code so I can edit the docs and code together in the IDE.
>> I produce the manual using Maven within the IDE.
>>
>> This makes it easier to keep both in synch by changing whichever file is wrong. Sometimes I write the manual topic first so I capture the spec
>> before coding it and sometimes I think of good ideas while coding that changes the topic in the manual so it is nice to have both files open in the
>> IDE at the same time.
>>
>> It does encourage me to write better specs since I have to think out and explain in plain language what the new feature is going to do for the user
>> and clearly describe the meaning and possible ranges of values of each of the configuration parameters.
>>
>> I also feel better knowing that the effort spent on writing a clear spec will save (or eliminate) documentation effort later. Counters the WISCY
>> syndrome.
>>
>>>> I'm focussing on the approach first. I think that once we have had the
>>>> discussion about that and reach a concensus can we start discussions around
>>>> the technology and options to achieve it.
>>>>
>>>> Thanks
>>>> Sharan
>>>>
>>> Regards,
>>>
>>> Michael Brohl
>>> ecomify GmbH
>>> www.ecomify.de
>>>
>>
>

[Jacques Le Roux]

Another interesting opinion: http://www.neveruntilnow.com/asciidoctor/

Jacques

Le 28/05/2015 13:19, Jacques Le Roux a écrit :

> I'm still undecided on this, but I feel AsciiDoc is "slowly" gaining interest see http://www.artima.com/forums/flat.jsp?forum=106&thread=361787 It's
> the same spirit than Json againt XML...Though Markdown is not XML, but Dita is. Also AsciiDoc offers a lot of export possibilities, see
> http://en.wikipedia.org/wiki/Comparison_of_document_markup_languages
>
> Anyway we will need a community consensus...
>
> Jacques
>
> Le 28/05/2015 12:29, Taher Alkhateeb a écrit :
>> Hi Jacques and all,
>>
>> If you want a simple documentation language then markdown comes to mind. It is simple, beautiful, mature and well supported in terms of tools and
>> probably covers the 90% of cases needed by everyone. So throwing another suggestion in the mix.
>>
>> Taher Alkhateeb
>>
>> ----- Original Message -----
>>
>> From: "Jacques Le Roux" <[hidden email]>
>> To: [hidden email]
>> Sent: Thursday, 28 May, 2015 12:51:13 PM
>> Subject: Re: [DISCUSSION] OFBiz Online Documentation
>>
>> That sounds quite an interesting way Ron.
>> I also believe we should get rid of DocBook in favour of DITTA or maybe even AsciiDoc (the last smart guy) as we already discussed at the bottom of
>> https://issues.apache.org/jira/browse/OFBIZ-4941
>> I also like the idea of separating the documentation from the project (Yippee our 1st sub-project Ron ;) ).
>> Finally, like I said in OFBIZ-4941 I HATE CONFLUENCE, but also, like outlined Sharan (damn can't find the link again), it has a lot of features,
>> notably when it comes to transform formats... and anyway it's our wiki support...
>>
>> Jacques
>>
>> Le 27/05/2015 17:55, Ron Wheeler a écrit :
>>> On 27/05/2015 10:50 AM, Michael Brohl wrote:
>>>> Hi Sharan,
>>>>
>>>> I had not the time to think more about your proposal but I can quickly answer your followup questions, see inline...
>>>>
>>>> Am 27.05.15 um 15:34 schrieb Sharan-F:
>>>>> Hi All
>>>>>
>>>>> I'm still looking for some community feedback on this proposal and approach
>>>>> and now I have a couple of extra questions.
>>>>>
>>>>> To any OFBiz Service providers out there – how do you manage the online help
>>>>> when you install or implement OFBiz? (Is it left as it is, do you remove it
>>>>> or do you create some new online help?)
>>>> In most of our projects, the existing online help is not used at all. The nature of our projects are mostly eCommerce and portal systems with
>>>> another ERP backend like SAP. So the OFBiz backend is either not used at all or only a small part is used. We do trainings with the end users then
>>>> and sometimes write some kind of manual which describes the backend use in context to the customer specific processes.
>>>>
>>>> I think there was only one project in the past 13 years which used the online help with partly modified texts.
>>> This is where DITA would be a big help since you could customize the topics that you need to change and leave the rest as is.
>>> I do this with our ADTransform product wherein I write a DITAMAP for a customer that pulls in common topics from the main manual library and
>>> customized topics written for each customer where we are providing the ETVL scripts and want to document the customers particular ETVL workflow.
>>>
>>> This short article introduces a good methodology for handling language customization.
>>> http://www.technical-writer.org/technical-communication/dita-xml-open-toolkit-multilingual-documentation-projects-tutorial-script-linux-bash/
>>> It probably overly detailed for this point in the discussion but I did want to point out how a single overall map can be used to produce manuals in
>>> different languages that are guaranteed to at least contain the same topics.
>>> It also shows how a multilingual manual would be set up as a project and generated (it shows the linux command line not the IDE as I would
>>> recommend) for those who like to get into the nuts and bolts early.
>>>
>>>
>>>>> To the general community at large - what is the overall feeling about
>>>>> extracting the online help, updating it and then packaging it as a separate
>>>>> project deliverable that can be easily integrated back into OFBiz?
>>>> Mmmhh, we have to make sure that the contents of the online help are in sync with the development and that it is easily editable for project
>>>> specific changes. Then I'm fine with it.
>>> For our ADTransform ETVL product which is a batch process(no on-line help possible or needed) , I use DITA for the manual and edit it in my IDE and
>>> store it as an SVN (I know that I am old fashioned!) project with my code so I can edit the docs and code together in the IDE.
>>> I produce the manual using Maven within the IDE.
>>>
>>> This makes it easier to keep both in synch by changing whichever file is wrong. Sometimes I write the manual topic first so I capture the spec
>>> before coding it and sometimes I think of good ideas while coding that changes the topic in the manual so it is nice to have both files open in the
>>> IDE at the same time.
>>>
>>> It does encourage me to write better specs since I have to think out and explain in plain language what the new feature is going to do for the user
>>> and clearly describe the meaning and possible ranges of values of each of the configuration parameters.
>>>
>>> I also feel better knowing that the effort spent on writing a clear spec will save (or eliminate) documentation effort later. Counters the WISCY
>>> syndrome.
>>>
>>>>> I'm focussing on the approach first. I think that once we have had the
>>>>> discussion about that and reach a concensus can we start discussions around
>>>>> the technology and options to achieve it.
>>>>>
>>>>> Thanks
>>>>> Sharan
>>>>>
>>>> Regards,
>>>>
>>>> Michael Brohl
>>>> ecomify GmbH
>>>> www.ecomify.de
>>>>
>>>
>>
>

[Jacques Le Roux]

And finally:
Read theStandardization section at http://en.wikipedia.org/wiki/Markdown
Also this one is maybe a bit biased (done by Dan Allen who supports AsciiDOc) but still an interesting comparison:
https://gist.github.com/mojavelinux/5870367
check
Asciidoc https://gist.githubusercontent.com/mojavelinux/5870367/raw/014804bf061baad6983ade6878484b9c0931da5b/gfm-vs-asciidoc.asciidoc
vs
Markdown https://github.github.com/github-flavored-markdown/sample_content.html

Jacques

Le 28/05/2015 13:24, Jacques Le Roux a écrit :

> Another interesting opinion: http://www.neveruntilnow.com/asciidoctor/
>
> Jacques
>
> Le 28/05/2015 13:19, Jacques Le Roux a écrit :
>> I'm still undecided on this, but I feel AsciiDoc is "slowly" gaining interest see http://www.artima.com/forums/flat.jsp?forum=106&thread=361787 
>> It's the same spirit than Json againt XML...Though Markdown is not XML, but Dita is. Also AsciiDoc offers a lot of export possibilities, see
>> http://en.wikipedia.org/wiki/Comparison_of_document_markup_languages
>>
>> Anyway we will need a community consensus...
>>
>> Jacques
>>
>> Le 28/05/2015 12:29, Taher Alkhateeb a écrit :
>>> Hi Jacques and all,
>>>
>>> If you want a simple documentation language then markdown comes to mind. It is simple, beautiful, mature and well supported in terms of tools and
>>> probably covers the 90% of cases needed by everyone. So throwing another suggestion in the mix.
>>>
>>> Taher Alkhateeb
>>>
>>> ----- Original Message -----
>>>
>>> From: "Jacques Le Roux" <[hidden email]>
>>> To: [hidden email]
>>> Sent: Thursday, 28 May, 2015 12:51:13 PM
>>> Subject: Re: [DISCUSSION] OFBiz Online Documentation
>>>
>>> That sounds quite an interesting way Ron.
>>> I also believe we should get rid of DocBook in favour of DITTA or maybe even AsciiDoc (the last smart guy) as we already discussed at the bottom of
>>> https://issues.apache.org/jira/browse/OFBIZ-4941
>>> I also like the idea of separating the documentation from the project (Yippee our 1st sub-project Ron ;) ).
>>> Finally, like I said in OFBIZ-4941 I HATE CONFLUENCE, but also, like outlined Sharan (damn can't find the link again), it has a lot of features,
>>> notably when it comes to transform formats... and anyway it's our wiki support...
>>>
>>> Jacques
>>>
>>> Le 27/05/2015 17:55, Ron Wheeler a écrit :
>>>> On 27/05/2015 10:50 AM, Michael Brohl wrote:
>>>>> Hi Sharan,
>>>>>
>>>>> I had not the time to think more about your proposal but I can quickly answer your followup questions, see inline...
>>>>>
>>>>> Am 27.05.15 um 15:34 schrieb Sharan-F:
>>>>>> Hi All
>>>>>>
>>>>>> I'm still looking for some community feedback on this proposal and approach
>>>>>> and now I have a couple of extra questions.
>>>>>>
>>>>>> To any OFBiz Service providers out there – how do you manage the online help
>>>>>> when you install or implement OFBiz? (Is it left as it is, do you remove it
>>>>>> or do you create some new online help?)
>>>>> In most of our projects, the existing online help is not used at all. The nature of our projects are mostly eCommerce and portal systems with
>>>>> another ERP backend like SAP. So the OFBiz backend is either not used at all or only a small part is used. We do trainings with the end users then
>>>>> and sometimes write some kind of manual which describes the backend use in context to the customer specific processes.
>>>>>
>>>>> I think there was only one project in the past 13 years which used the online help with partly modified texts.
>>>> This is where DITA would be a big help since you could customize the topics that you need to change and leave the rest as is.
>>>> I do this with our ADTransform product wherein I write a DITAMAP for a customer that pulls in common topics from the main manual library and
>>>> customized topics written for each customer where we are providing the ETVL scripts and want to document the customers particular ETVL workflow.
>>>>
>>>> This short article introduces a good methodology for handling language customization.
>>>> http://www.technical-writer.org/technical-communication/dita-xml-open-toolkit-multilingual-documentation-projects-tutorial-script-linux-bash/
>>>> It probably overly detailed for this point in the discussion but I did want to point out how a single overall map can be used to produce manuals in
>>>> different languages that are guaranteed to at least contain the same topics.
>>>> It also shows how a multilingual manual would be set up as a project and generated (it shows the linux command line not the IDE as I would
>>>> recommend) for those who like to get into the nuts and bolts early.
>>>>
>>>>
>>>>>> To the general community at large - what is the overall feeling about
>>>>>> extracting the online help, updating it and then packaging it as a separate
>>>>>> project deliverable that can be easily integrated back into OFBiz?
>>>>> Mmmhh, we have to make sure that the contents of the online help are in sync with the development and that it is easily editable for project
>>>>> specific changes. Then I'm fine with it.
>>>> For our ADTransform ETVL product which is a batch process(no on-line help possible or needed) , I use DITA for the manual and edit it in my IDE and
>>>> store it as an SVN (I know that I am old fashioned!) project with my code so I can edit the docs and code together in the IDE.
>>>> I produce the manual using Maven within the IDE.
>>>>
>>>> This makes it easier to keep both in synch by changing whichever file is wrong. Sometimes I write the manual topic first so I capture the spec
>>>> before coding it and sometimes I think of good ideas while coding that changes the topic in the manual so it is nice to have both files open in the
>>>> IDE at the same time.
>>>>
>>>> It does encourage me to write better specs since I have to think out and explain in plain language what the new feature is going to do for the user
>>>> and clearly describe the meaning and possible ranges of values of each of the configuration parameters.
>>>>
>>>> I also feel better knowing that the effort spent on writing a clear spec will save (or eliminate) documentation effort later. Counters the WISCY
>>>> syndrome.
>>>>
>>>>>> I'm focussing on the approach first. I think that once we have had the
>>>>>> discussion about that and reach a concensus can we start discussions around
>>>>>> the technology and options to achieve it.
>>>>>>
>>>>>> Thanks
>>>>>> Sharan
>>>>>>
>>>>> Regards,
>>>>>
>>>>> Michael Brohl
>>>>> ecomify GmbH
>>>>> www.ecomify.de
>>>>>
>>>>
>>>
>>
>

[Pierre Smits]

In stead of adding another set of complexities and potential orphaned
endeavours (asciidoc, markdown, etc) to the mix of
https://www.openhub.net/p/Apache-OFBiz/analyses/latest/languages_summary#dingus-row,
I suggest applying something that contributors already have experience
and/or are comfortable with.

Please also remember that - to state the obvious: as this constitutes a
'code-change' - consensus is required.

Best regards,



Pierre Smits

*ORRTIZ.COM <http://www.orrtiz.com>*
Services & Solutions for Cloud-
Based Manufacturing, Professional
Services and Retail & Trade
http://www.orrtiz.com

On Thu, May 28, 2015 at 1:44 PM, Jacques Le Roux <
[hidden email]> wrote:

> And finally:
> Read theStandardization section at http://en.wikipedia.org/wiki/Markdown
> Also this one is maybe a bit biased (done by Dan Allen who supports
> AsciiDOc) but still an interesting comparison:
> https://gist.github.com/mojavelinux/5870367
> check
> Asciidoc
> https://gist.githubusercontent.com/mojavelinux/5870367/raw/014804bf061baad6983ade6878484b9c0931da5b/gfm-vs-asciidoc.asciidoc
> vs
> Markdown
> https://github.github.com/github-flavored-markdown/sample_content.html
>
> Jacques
>
>
> Le 28/05/2015 13:24, Jacques Le Roux a écrit :
>
>> Another interesting opinion: http://www.neveruntilnow.com/asciidoctor/
>>
>> Jacques
>>
>> Le 28/05/2015 13:19, Jacques Le Roux a écrit :
>>
>>> I'm still undecided on this, but I feel AsciiDoc is "slowly" gaining
>>> interest see
>>> http://www.artima.com/forums/flat.jsp?forum=106&thread=361787 It's the
>>> same spirit than Json againt XML...Though Markdown is not XML, but Dita is.
>>> Also AsciiDoc offers a lot of export possibilities, see
>>> http://en.wikipedia.org/wiki/Comparison_of_document_markup_languages
>>>
>>> Anyway we will need a community consensus...
>>>
>>> Jacques
>>>
>>> Le 28/05/2015 12:29, Taher Alkhateeb a écrit :
>>>
>>>> Hi Jacques and all,
>>>>
>>>> If you want a simple documentation language then markdown comes to
>>>> mind. It is simple, beautiful, mature and well supported in terms of tools
>>>> and probably covers the 90% of cases needed by everyone. So throwing
>>>> another suggestion in the mix.
>>>>
>>>> Taher Alkhateeb
>>>>
>>>> ----- Original Message -----
>>>>
>>>> From: "Jacques Le Roux" <[hidden email]>
>>>> To: [hidden email]
>>>> Sent: Thursday, 28 May, 2015 12:51:13 PM
>>>> Subject: Re: [DISCUSSION] OFBiz Online Documentation
>>>>
>>>> That sounds quite an interesting way Ron.
>>>> I also believe we should get rid of DocBook in favour of DITTA or maybe
>>>> even AsciiDoc (the last smart guy) as we already discussed at the bottom of
>>>> https://issues.apache.org/jira/browse/OFBIZ-4941
>>>> I also like the idea of separating the documentation from the project
>>>> (Yippee our 1st sub-project Ron ;) ).
>>>> Finally, like I said in OFBIZ-4941 I HATE CONFLUENCE, but also, like
>>>> outlined Sharan (damn can't find the link again), it has a lot of features,
>>>> notably when it comes to transform formats... and anyway it's our wiki
>>>> support...
>>>>
>>>> Jacques
>>>>
>>>> Le 27/05/2015 17:55, Ron Wheeler a écrit :
>>>>
>>>>> On 27/05/2015 10:50 AM, Michael Brohl wrote:
>>>>>
>>>>>> Hi Sharan,
>>>>>>
>>>>>> I had not the time to think more about your proposal but I can
>>>>>> quickly answer your followup questions, see inline...
>>>>>>
>>>>>> Am 27.05.15 um 15:34 schrieb Sharan-F:
>>>>>>
>>>>>>> Hi All
>>>>>>>
>>>>>>> I'm still looking for some community feedback on this proposal and
>>>>>>> approach
>>>>>>> and now I have a couple of extra questions.
>>>>>>>
>>>>>>> To any OFBiz Service providers out there – how do you manage the
>>>>>>> online help
>>>>>>> when you install or implement OFBiz? (Is it left as it is, do you
>>>>>>> remove it
>>>>>>> or do you create some new online help?)
>>>>>>>
>>>>>> In most of our projects, the existing online help is not used at all.
>>>>>> The nature of our projects are mostly eCommerce and portal systems with
>>>>>> another ERP backend like SAP. So the OFBiz backend is either not used
>>>>>> at all or only a small part is used. We do trainings with the end users then
>>>>>> and sometimes write some kind of manual which describes the backend
>>>>>> use in context to the customer specific processes.
>>>>>>
>>>>>> I think there was only one project in the past 13 years which used
>>>>>> the online help with partly modified texts.
>>>>>>
>>>>> This is where DITA would be a big help since you could customize the
>>>>> topics that you need to change and leave the rest as is.
>>>>> I do this with our ADTransform product wherein I write a DITAMAP for a
>>>>> customer that pulls in common topics from the main manual library and
>>>>> customized topics written for each customer where we are providing the
>>>>> ETVL scripts and want to document the customers particular ETVL workflow.
>>>>>
>>>>> This short article introduces a good methodology for handling language
>>>>> customization.
>>>>>
>>>>> http://www.technical-writer.org/technical-communication/dita-xml-open-toolkit-multilingual-documentation-projects-tutorial-script-linux-bash/
>>>>> It probably overly detailed for this point in the discussion but I did
>>>>> want to point out how a single overall map can be used to produce manuals in
>>>>> different languages that are guaranteed to at least contain the same
>>>>> topics.
>>>>> It also shows how a multilingual manual would be set up as a project
>>>>> and generated (it shows the linux command line not the IDE as I would
>>>>> recommend) for those who like to get into the nuts and bolts early.
>>>>>
>>>>>
>>>>>  To the general community at large - what is the overall feeling about
>>>>>>> extracting the online help, updating it and then packaging it as a
>>>>>>> separate
>>>>>>> project deliverable that can be easily integrated back into OFBiz?
>>>>>>>
>>>>>> Mmmhh, we have to make sure that the contents of the online help are
>>>>>> in sync with the development and that it is easily editable for project
>>>>>> specific changes. Then I'm fine with it.
>>>>>>
>>>>> For our ADTransform ETVL product which is a batch process(no on-line
>>>>> help possible or needed) , I use DITA for the manual and edit it in my IDE
>>>>> and
>>>>> store it as an SVN (I know that I am old fashioned!) project with my
>>>>> code so I can edit the docs and code together in the IDE.
>>>>> I produce the manual using Maven within the IDE.
>>>>>
>>>>> This makes it easier to keep both in synch by changing whichever file
>>>>> is wrong. Sometimes I write the manual topic first so I capture the spec
>>>>> before coding it and sometimes I think of good ideas while coding that
>>>>> changes the topic in the manual so it is nice to have both files open in the
>>>>> IDE at the same time.
>>>>>
>>>>> It does encourage me to write better specs since I have to think out
>>>>> and explain in plain language what the new feature is going to do for the
>>>>> user
>>>>> and clearly describe the meaning and possible ranges of values of each
>>>>> of the configuration parameters.
>>>>>
>>>>> I also feel better knowing that the effort spent on writing a clear
>>>>> spec will save (or eliminate) documentation effort later. Counters the WISCY
>>>>> syndrome.
>>>>>
>>>>>  I'm focussing on the approach first. I think that once we have had the
>>>>>>> discussion about that and reach a concensus can we start discussions
>>>>>>> around
>>>>>>> the technology and options to achieve it.
>>>>>>>
>>>>>>> Thanks
>>>>>>> Sharan
>>>>>>>
>>>>>>>  Regards,
>>>>>>
>>>>>> Michael Brohl
>>>>>> ecomify GmbH
>>>>>> www.ecomify.de
>>>>>>
>>>>>>
>>>>>
>>>>
>>>
>>

[marcopaul]

The OS X UI guidelines doc is a fantastic read. It concisely sums up many modern Engineering Psychology best practices.

Anyone who is designing front-end or back-end screens should be familiar with at least the basics.
 
https://developer.apple.com/library/mac/documentation/UserExperience/Conceptual/OSXHIGuidelines/StartStop.html#//apple_ref/doc/uid/20000957-CH5-SW1 <https://developer.apple.com/library/mac/documentation/UserExperience/Conceptual/OSXHIGuidelines/StartStop.html#//apple_ref/doc/uid/20000957-CH5-SW1>

While there are plenty of OS X-specific guidelines in there, this document is full of great general guidelines that apply to any software application regardless of platform. The Menus, UI Design Basics, and Controls and Views sections are particularly interesting.

—Paul

> On May 28, 2015, at 4:40 AM, Jacques Le Roux <[hidden email]> wrote:
>
> Le 27/05/2015 16:41, Paul Mandeltort a écrit :
>> End user here - online help has always been a weak spot for OFbiz.
>>
>> I would suggest putting more effort into making things self-documenting whenever possible. For example, adding descriptive tool tips to what buttons do ("clicking this will process the order and notify the customer") and more action-oriented names for things. Apple has great UI guidelines for making these kinds of things self documenting.
>
> Due to the nature of the projects we (integrators, service providers) support (as eg well explained Michael) that sounds like a great suggestion to me. Would you have a link to "Apple has great UI guidelines"?
>
> Thanks
>
> Jacques
>
>>
>>
>> --Paul (From Mobile)
>>
>>> On May 27, 2015, at 8:34 AM, Sharan-F <[hidden email]> wrote:
>>>
>>> Hi All
>>>
>>> I'm still looking for some community feedback on this proposal and approach
>>> and now I have a couple of extra questions.
>>>
>>> To any OFBiz Service providers out there – how do you manage the online help
>>> when you install or implement OFBiz? (Is it left as it is, do you remove it
>>> or do you create some new online help?)
>>>
>>> To the general community at large - what is the overall feeling about
>>> extracting the online help, updating it and then packaging it as a separate
>>> project deliverable that can be easily integrated back into OFBiz?
>>>
>>> I'm focussing on the approach first. I think that once we have had the
>>> discussion about that and reach a concensus can we start discussions around
>>> the technology and options to achieve it.
>>>
>>> Thanks
>>> Sharan
>>>
>>>
>>>
>>> --
>>> View this message in context: http://ofbiz.135035.n4.nabble.com/DISCUSSION-OFBiz-Online-Documentation-tp4668869p4669054.html
>>> Sent from the OFBiz - User mailing list archive at Nabble.com.
>>

[Todd Thorner]

I'm pretty much sitting this one out (seems to have jumped right into
the tech selection and I don't understand OFBiz well enough yet to be
useful as a writer-contributor so I wouldn't be able to offer much
quality input), but for what it's worth the most important
considerations for a typing architecture are:

1. The project's business needs (e.g. "No XML files!")
2. Making sure the single-sourced files can be puked out into as many
useful end user formats as possible (e.g. context-sensitive help, wiki,
etc.)
3. Making sure a maximum number of writer-contributors can hit the
proverbial ground running without needing to learn new processes

One thing I can offer for now is editing skills, but that involves
potential toe-stepping.  Perhaps I could transform that solid Prezi
presentation into Sozi format so its SVG output could be embedded into
any OFBiz web page.  If the original author is cool with that (can't
remember who it was), let me know.



On 15-05-28 04:44 AM, Jacques Le Roux wrote:

> And finally:
> Read theStandardization section at http://en.wikipedia.org/wiki/Markdown
> Also this one is maybe a bit biased (done by Dan Allen who supports
> AsciiDOc) but still an interesting comparison:
> https://gist.github.com/mojavelinux/5870367
> check
> Asciidoc
> https://gist.githubusercontent.com/mojavelinux/5870367/raw/014804bf061baad6983ade6878484b9c0931da5b/gfm-vs-asciidoc.asciidoc
>
> vs
> Markdown
> https://github.github.com/github-flavored-markdown/sample_content.html
>
> Jacques
>
> Le 28/05/2015 13:24, Jacques Le Roux a écrit :
>> Another interesting opinion: http://www.neveruntilnow.com/asciidoctor/
>>
>> Jacques
>>
>> Le 28/05/2015 13:19, Jacques Le Roux a écrit :
>>> I'm still undecided on this, but I feel AsciiDoc is "slowly" gaining
>>> interest see
>>> http://www.artima.com/forums/flat.jsp?forum=106&thread=361787 It's
>>> the same spirit than Json againt XML...Though Markdown is not XML,
>>> but Dita is. Also AsciiDoc offers a lot of export possibilities, see
>>> http://en.wikipedia.org/wiki/Comparison_of_document_markup_languages
>>>
>>> Anyway we will need a community consensus...
>>>
>>> Jacques
>>>
>>> Le 28/05/2015 12:29, Taher Alkhateeb a écrit :
>>>> Hi Jacques and all,
>>>>
>>>> If you want a simple documentation language then markdown comes to
>>>> mind. It is simple, beautiful, mature and well supported in terms of
>>>> tools and probably covers the 90% of cases needed by everyone. So
>>>> throwing another suggestion in the mix.
>>>>
>>>> Taher Alkhateeb
>>>>
>>>> ----- Original Message -----
>>>>
>>>> From: "Jacques Le Roux" <[hidden email]>
>>>> To: [hidden email]
>>>> Sent: Thursday, 28 May, 2015 12:51:13 PM
>>>> Subject: Re: [DISCUSSION] OFBiz Online Documentation
>>>>
>>>> That sounds quite an interesting way Ron.
>>>> I also believe we should get rid of DocBook in favour of DITTA or
>>>> maybe even AsciiDoc (the last smart guy) as we already discussed at
>>>> the bottom of
>>>> https://issues.apache.org/jira/browse/OFBIZ-4941
>>>> I also like the idea of separating the documentation from the
>>>> project (Yippee our 1st sub-project Ron ;) ).
>>>> Finally, like I said in OFBIZ-4941 I HATE CONFLUENCE, but also, like
>>>> outlined Sharan (damn can't find the link again), it has a lot of
>>>> features,
>>>> notably when it comes to transform formats... and anyway it's our
>>>> wiki support...
>>>>
>>>> Jacques
>>>>
>>>> Le 27/05/2015 17:55, Ron Wheeler a écrit :
>>>>> On 27/05/2015 10:50 AM, Michael Brohl wrote:
>>>>>> Hi Sharan,
>>>>>>
>>>>>> I had not the time to think more about your proposal but I can
>>>>>> quickly answer your followup questions, see inline...
>>>>>>
>>>>>> Am 27.05.15 um 15:34 schrieb Sharan-F:
>>>>>>> Hi All
>>>>>>>
>>>>>>> I'm still looking for some community feedback on this proposal
>>>>>>> and approach
>>>>>>> and now I have a couple of extra questions.
>>>>>>>
>>>>>>> To any OFBiz Service providers out there – how do you manage the
>>>>>>> online help
>>>>>>> when you install or implement OFBiz? (Is it left as it is, do you
>>>>>>> remove it
>>>>>>> or do you create some new online help?)
>>>>>> In most of our projects, the existing online help is not used at
>>>>>> all. The nature of our projects are mostly eCommerce and portal
>>>>>> systems with
>>>>>> another ERP backend like SAP. So the OFBiz backend is either not
>>>>>> used at all or only a small part is used. We do trainings with the
>>>>>> end users then
>>>>>> and sometimes write some kind of manual which describes the
>>>>>> backend use in context to the customer specific processes.
>>>>>>
>>>>>> I think there was only one project in the past 13 years which used
>>>>>> the online help with partly modified texts.
>>>>> This is where DITA would be a big help since you could customize
>>>>> the topics that you need to change and leave the rest as is.
>>>>> I do this with our ADTransform product wherein I write a DITAMAP
>>>>> for a customer that pulls in common topics from the main manual
>>>>> library and
>>>>> customized topics written for each customer where we are providing
>>>>> the ETVL scripts and want to document the customers particular ETVL
>>>>> workflow.
>>>>>
>>>>> This short article introduces a good methodology for handling
>>>>> language customization.
>>>>> http://www.technical-writer.org/technical-communication/dita-xml-open-toolkit-multilingual-documentation-projects-tutorial-script-linux-bash/
>>>>>
>>>>> It probably overly detailed for this point in the discussion but I
>>>>> did want to point out how a single overall map can be used to
>>>>> produce manuals in
>>>>> different languages that are guaranteed to at least contain the
>>>>> same topics.
>>>>> It also shows how a multilingual manual would be set up as a
>>>>> project and generated (it shows the linux command line not the IDE
>>>>> as I would
>>>>> recommend) for those who like to get into the nuts and bolts early.
>>>>>
>>>>>
>>>>>>> To the general community at large - what is the overall feeling
>>>>>>> about
>>>>>>> extracting the online help, updating it and then packaging it as
>>>>>>> a separate
>>>>>>> project deliverable that can be easily integrated back into OFBiz?
>>>>>> Mmmhh, we have to make sure that the contents of the online help
>>>>>> are in sync with the development and that it is easily editable
>>>>>> for project
>>>>>> specific changes. Then I'm fine with it.
>>>>> For our ADTransform ETVL product which is a batch process(no
>>>>> on-line help possible or needed) , I use DITA for the manual and
>>>>> edit it in my IDE and
>>>>> store it as an SVN (I know that I am old fashioned!) project with
>>>>> my code so I can edit the docs and code together in the IDE.
>>>>> I produce the manual using Maven within the IDE.
>>>>>
>>>>> This makes it easier to keep both in synch by changing whichever
>>>>> file is wrong. Sometimes I write the manual topic first so I
>>>>> capture the spec
>>>>> before coding it and sometimes I think of good ideas while coding
>>>>> that changes the topic in the manual so it is nice to have both
>>>>> files open in the
>>>>> IDE at the same time.
>>>>>
>>>>> It does encourage me to write better specs since I have to think
>>>>> out and explain in plain language what the new feature is going to
>>>>> do for the user
>>>>> and clearly describe the meaning and possible ranges of values of
>>>>> each of the configuration parameters.
>>>>>
>>>>> I also feel better knowing that the effort spent on writing a clear
>>>>> spec will save (or eliminate) documentation effort later. Counters
>>>>> the WISCY
>>>>> syndrome.
>>>>>
>>>>>>> I'm focussing on the approach first. I think that once we have
>>>>>>> had the
>>>>>>> discussion about that and reach a concensus can we start
>>>>>>> discussions around
>>>>>>> the technology and options to achieve it.
>>>>>>>
>>>>>>> Thanks
>>>>>>> Sharan
>>>>>>>
>>>>>> Regards,
>>>>>>
>>>>>> Michael Brohl
>>>>>> ecomify GmbH
>>>>>> www.ecomify.de
>>>>>>
>>>>>
>>>>
>>>
>>

[Michael Brohl-3]

Todd,

do you mean this Prezi
http://prezi.com/qqp54gt46pn_/apache-ofbiz-development/ from Jad El Omeiri?


Am 28.05.15 um 16:52 schrieb Todd Thorner:

> I'm pretty much sitting this one out (seems to have jumped right into
> the tech selection and I don't understand OFBiz well enough yet to be
> useful as a writer-contributor so I wouldn't be able to offer much
> quality input), but for what it's worth the most important
> considerations for a typing architecture are:
>
> 1. The project's business needs (e.g. "No XML files!")
> 2. Making sure the single-sourced files can be puked out into as many
> useful end user formats as possible (e.g. context-sensitive help, wiki,
> etc.)
> 3. Making sure a maximum number of writer-contributors can hit the
> proverbial ground running without needing to learn new processes
>
> One thing I can offer for now is editing skills, but that involves
> potential toe-stepping.  Perhaps I could transform that solid Prezi
> presentation into Sozi format so its SVG output could be embedded into
> any OFBiz web page.  If the original author is cool with that (can't
> remember who it was), let me know.
>
>

[Todd Thorner]

I have yet to take a look (or another look), but that seems about right
(I think the presentation was mainly about data models).  Is Mr. El
Omeiri still active on this ml?

Also, the anal part of me needs to edit my bit about editing skills to
read "editing skill."  Ha.



On 15-05-28 08:07 AM, Michael Brohl wrote:

> Todd,
>
> do you mean this Prezi
> http://prezi.com/qqp54gt46pn_/apache-ofbiz-development/ from Jad El Omeiri?
>
>
> Am 28.05.15 um 16:52 schrieb Todd Thorner:
>> I'm pretty much sitting this one out (seems to have jumped right into
>> the tech selection and I don't understand OFBiz well enough yet to be
>> useful as a writer-contributor so I wouldn't be able to offer much
>> quality input), but for what it's worth the most important
>> considerations for a typing architecture are:
>>
>> 1. The project's business needs (e.g. "No XML files!")
>> 2. Making sure the single-sourced files can be puked out into as many
>> useful end user formats as possible (e.g. context-sensitive help, wiki,
>> etc.)
>> 3. Making sure a maximum number of writer-contributors can hit the
>> proverbial ground running without needing to learn new processes
>>
>> One thing I can offer for now is editing skills, but that involves
>> potential toe-stepping.  Perhaps I could transform that solid Prezi
>> presentation into Sozi format so its SVG output could be embedded into
>> any OFBiz web page.  If the original author is cool with that (can't
>> remember who it was), let me know.
>>
>>
>
>

[Ron Wheeler]

One of the things that concerns me about AsciiDoc is that some
formatting is mixed in with content.
This makes reuse problematic.
I am not sure that IDE's can validate AsciiDoc documents or provide
"code" assist/autocompletion which is possible for IDE's such as Eclipse
with DITA.

I am not sure that translation support exists for AsciiDoc as fully as
it does for DITA.

I find the wide variety of characters used to identify markup to be
disconcerting to someone who is used to XML tags.
In DITA, if it is an XML tag it is DITA anything else is not.
In AsciiDoc many different characters are used to signal a ASCIIDoc
notation and some depend on position in the text ("." in column 1)

I maintain websites in MediaWiki, Confluence and Wordpress.

I would still go with DITA for documentation because of its simplicity
and rigour in authoring and flexibility in output.

It is going to be much better for Integrators that need to produce
marketing materials, RFP responses and custom end-user documentation
that could be largely composed of topics from the shared OFBiz library
of topics simply by defining a map that calls up the topics that you
need in the sequence required and applying a format that matches the
output requirements.
I just don't see how the alternatives that are being discussed can do
this and this seems to be a major value that will motivate people to
contribute.

Ron

On 28/05/2015 7:44 AM, Jacques Le Roux wrote:

> And finally:
> Read theStandardization section at http://en.wikipedia.org/wiki/Markdown
> Also this one is maybe a bit biased (done by Dan Allen who supports
> AsciiDOc) but still an interesting comparison:
> https://gist.github.com/mojavelinux/5870367
> check
> Asciidoc
> https://gist.githubusercontent.com/mojavelinux/5870367/raw/014804bf061baad6983ade6878484b9c0931da5b/gfm-vs-asciidoc.asciidoc
> vs
> Markdown
> https://github.github.com/github-flavored-markdown/sample_content.html
>
> Jacques
>
> Le 28/05/2015 13:24, Jacques Le Roux a écrit :
>> Another interesting opinion: http://www.neveruntilnow.com/asciidoctor/
>>
>> Jacques
>>
>> Le 28/05/2015 13:19, Jacques Le Roux a écrit :
>>> I'm still undecided on this, but I feel AsciiDoc is "slowly" gaining
>>> interest see
>>> http://www.artima.com/forums/flat.jsp?forum=106&thread=361787 It's
>>> the same spirit than Json againt XML...Though Markdown is not XML,
>>> but Dita is. Also AsciiDoc offers a lot of export possibilities, see
>>> http://en.wikipedia.org/wiki/Comparison_of_document_markup_languages
>>>
>>> Anyway we will need a community consensus...
>>>
>>> Jacques
>>>
>>> Le 28/05/2015 12:29, Taher Alkhateeb a écrit :
>>>> Hi Jacques and all,
>>>>
>>>> If you want a simple documentation language then markdown comes to
>>>> mind. It is simple, beautiful, mature and well supported in terms
>>>> of tools and probably covers the 90% of cases needed by everyone.
>>>> So throwing another suggestion in the mix.
>>>>
>>>> Taher Alkhateeb
>>>>
>>>> ----- Original Message -----
>>>>
>>>> From: "Jacques Le Roux" <[hidden email]>
>>>> To: [hidden email]
>>>> Sent: Thursday, 28 May, 2015 12:51:13 PM
>>>> Subject: Re: [DISCUSSION] OFBiz Online Documentation
>>>>
>>>> That sounds quite an interesting way Ron.
>>>> I also believe we should get rid of DocBook in favour of DITTA or
>>>> maybe even AsciiDoc (the last smart guy) as we already discussed at
>>>> the bottom of
>>>> https://issues.apache.org/jira/browse/OFBIZ-4941
>>>> I also like the idea of separating the documentation from the
>>>> project (Yippee our 1st sub-project Ron ;) ).
>>>> Finally, like I said in OFBIZ-4941 I HATE CONFLUENCE, but also,
>>>> like outlined Sharan (damn can't find the link again), it has a lot
>>>> of features,
>>>> notably when it comes to transform formats... and anyway it's our
>>>> wiki support...
>>>>
>>>> Jacques
>>>>
>>>> Le 27/05/2015 17:55, Ron Wheeler a écrit :
>>>>> On 27/05/2015 10:50 AM, Michael Brohl wrote:
>>>>>> Hi Sharan,
>>>>>>
>>>>>> I had not the time to think more about your proposal but I can
>>>>>> quickly answer your followup questions, see inline...
>>>>>>
>>>>>> Am 27.05.15 um 15:34 schrieb Sharan-F:
>>>>>>> Hi All
>>>>>>>
>>>>>>> I'm still looking for some community feedback on this proposal
>>>>>>> and approach
>>>>>>> and now I have a couple of extra questions.
>>>>>>>
>>>>>>> To any OFBiz Service providers out there – how do you manage the
>>>>>>> online help
>>>>>>> when you install or implement OFBiz? (Is it left as it is, do
>>>>>>> you remove it
>>>>>>> or do you create some new online help?)
>>>>>> In most of our projects, the existing online help is not used at
>>>>>> all. The nature of our projects are mostly eCommerce and portal
>>>>>> systems with
>>>>>> another ERP backend like SAP. So the OFBiz backend is either not
>>>>>> used at all or only a small part is used. We do trainings with
>>>>>> the end users then
>>>>>> and sometimes write some kind of manual which describes the
>>>>>> backend use in context to the customer specific processes.
>>>>>>
>>>>>> I think there was only one project in the past 13 years which
>>>>>> used the online help with partly modified texts.
>>>>> This is where DITA would be a big help since you could customize
>>>>> the topics that you need to change and leave the rest as is.
>>>>> I do this with our ADTransform product wherein I write a DITAMAP
>>>>> for a customer that pulls in common topics from the main manual
>>>>> library and
>>>>> customized topics written for each customer where we are providing
>>>>> the ETVL scripts and want to document the customers particular
>>>>> ETVL workflow.
>>>>>
>>>>> This short article introduces a good methodology for handling
>>>>> language customization.
>>>>> http://www.technical-writer.org/technical-communication/dita-xml-open-toolkit-multilingual-documentation-projects-tutorial-script-linux-bash/ 
>>>>>
>>>>> It probably overly detailed for this point in the discussion but I
>>>>> did want to point out how a single overall map can be used to
>>>>> produce manuals in
>>>>> different languages that are guaranteed to at least contain the
>>>>> same topics.
>>>>> It also shows how a multilingual manual would be set up as a
>>>>> project and generated (it shows the linux command line not the IDE
>>>>> as I would
>>>>> recommend) for those who like to get into the nuts and bolts early.
>>>>>
>>>>>
>>>>>>> To the general community at large - what is the overall feeling
>>>>>>> about
>>>>>>> extracting the online help, updating it and then packaging it as
>>>>>>> a separate
>>>>>>> project deliverable that can be easily integrated back into OFBiz?
>>>>>> Mmmhh, we have to make sure that the contents of the online help
>>>>>> are in sync with the development and that it is easily editable
>>>>>> for project
>>>>>> specific changes. Then I'm fine with it.
>>>>> For our ADTransform ETVL product which is a batch process(no
>>>>> on-line help possible or needed) , I use DITA for the manual and
>>>>> edit it in my IDE and
>>>>> store it as an SVN (I know that I am old fashioned!) project with
>>>>> my code so I can edit the docs and code together in the IDE.
>>>>> I produce the manual using Maven within the IDE.
>>>>>
>>>>> This makes it easier to keep both in synch by changing whichever
>>>>> file is wrong. Sometimes I write the manual topic first so I
>>>>> capture the spec
>>>>> before coding it and sometimes I think of good ideas while coding
>>>>> that changes the topic in the manual so it is nice to have both
>>>>> files open in the
>>>>> IDE at the same time.
>>>>>
>>>>> It does encourage me to write better specs since I have to think
>>>>> out and explain in plain language what the new feature is going to
>>>>> do for the user
>>>>> and clearly describe the meaning and possible ranges of values of
>>>>> each of the configuration parameters.
>>>>>
>>>>> I also feel better knowing that the effort spent on writing a
>>>>> clear spec will save (or eliminate) documentation effort later.
>>>>> Counters the WISCY
>>>>> syndrome.
>>>>>
>>>>>>> I'm focussing on the approach first. I think that once we have
>>>>>>> had the
>>>>>>> discussion about that and reach a concensus can we start
>>>>>>> discussions around
>>>>>>> the technology and options to achieve it.
>>>>>>>
>>>>>>> Thanks
>>>>>>> Sharan
>>>>>>>
>>>>>> Regards,
>>>>>>
>>>>>> Michael Brohl
>>>>>> ecomify GmbH
>>>>>> www.ecomify.de
>>>>>>
>>>>>
>>>>
>>>
>>
>

--
Ron Wheeler
President
Artifact Software Inc
email: [hidden email]
skype: ronaldmwheeler
phone: [phone], ext 102

[Jacques Le Roux]

Le 28/05/2015 20:16, Ron Wheeler a écrit :
> One of the things that concerns me about AsciiDoc is that some formatting is mixed in with content.
> This makes reuse problematic.
> I am not sure that IDE's can validate AsciiDoc documents or provide "code" assist/autocompletion which is possible for IDE's such as Eclipse with DITA.

That's an important point indeed. I used to have the same for DocBook with Oxygen in Eclipse (no longer Oxygen is now too expansive).
I found this https://www.eclipse.org/forums/index.php/t/482722/ https://bugs.eclipse.org/bugs/show_bug.cgi?id=418563 so seems to still be a WIP but
already available. I don't know how it compare to DITA in Eclipse in term of assist/autocompletion

> I am not sure that translation support exists for AsciiDoc as fully as it does for DITA.

I don't really know for import, what I know for sure is AsciiDoc export is wide since it can export to DocBook as an intermeditate format and we know
DocBook  can erxport a lot

> I find the wide variety of characters used to identify markup to be disconcerting to someone who is used to XML tags.

Yes that's another way.

> In DITA, if it is an XML tag it is DITA anything else is not.
> In AsciiDoc many different characters are used to signal a ASCIIDoc notation and some depend on position in the text ("." in column 1)

As long as you are in an IDE with autocompletion DITA is fine, I guess AsciiDoc beats it when you have only a simple text editor. It's a matter of
taste and it seems, like Json is more and more preferred to XML, some developers prefer AsciiDoc because it looks like code.

>
> I maintain websites in MediaWiki, Confluence and Wordpress.
>
> I would still go with DITA for documentation because of its simplicity and rigour in authoring and flexibility in output.

I'm not against to DITA, anyway it's a community choice... BTW are we sure we want to move from DocBook, and why?

> It is going to be much better for Integrators that need to produce marketing materials, RFP responses and custom end-user documentation that could
> be largely composed of topics from the shared OFBiz library of topics simply by defining a map that calls up the topics that you need in the
> sequence required and applying a format that matches the output requirements.
> I just don't see how the alternatives that are being discussed can do this and this seems to be a major value that will motivate people to contribute.

You know and use DITA professionally so you have arguments. I have no (at all) experience with AsciiDoc so I can't give good arguments. Could you
though explain what you mean by  "RFP responses and custom end-user documentation that could be largely composed of topics from the shared OFBiz
library of topics simply by defining a map that calls up the topics that you need"?  Notably what is exactly the "shared OFBiz library of topics"?

I just re-read the end of https://issues.apache.org/jira/browse/OFBIZ-4941 and this remembered me http://pandoc.org/
Are there free DocBook to Dita converters apart https://sourceforge.net/projects/dita-ot/ ?

Anyway we 1st need to be sure the community want to move from DocBook, (to eg DITA or AsciiDoc) and why...

Thanks

Jacques

>
> Ron
>
> On 28/05/2015 7:44 AM, Jacques Le Roux wrote:
>> And finally:
>> Read theStandardization section at http://en.wikipedia.org/wiki/Markdown
>> Also this one is maybe a bit biased (done by Dan Allen who supports AsciiDOc) but still an interesting comparison:
>> https://gist.github.com/mojavelinux/5870367
>> check
>> Asciidoc https://gist.githubusercontent.com/mojavelinux/5870367/raw/014804bf061baad6983ade6878484b9c0931da5b/gfm-vs-asciidoc.asciidoc
>> vs
>> Markdown https://github.github.com/github-flavored-markdown/sample_content.html
>>
>> Jacques
>>
>> Le 28/05/2015 13:24, Jacques Le Roux a écrit :
>>> Another interesting opinion: http://www.neveruntilnow.com/asciidoctor/
>>>
>>> Jacques
>>>
>>> Le 28/05/2015 13:19, Jacques Le Roux a écrit :
>>>> I'm still undecided on this, but I feel AsciiDoc is "slowly" gaining interest see http://www.artima.com/forums/flat.jsp?forum=106&thread=361787 
>>>> It's the same spirit than Json againt XML...Though Markdown is not XML, but Dita is. Also AsciiDoc offers a lot of export possibilities, see
>>>> http://en.wikipedia.org/wiki/Comparison_of_document_markup_languages
>>>>
>>>> Anyway we will need a community consensus...
>>>>
>>>> Jacques
>>>>
>>>> Le 28/05/2015 12:29, Taher Alkhateeb a écrit :
>>>>> Hi Jacques and all,
>>>>>
>>>>> If you want a simple documentation language then markdown comes to mind. It is simple, beautiful, mature and well supported in terms of tools
>>>>> and probably covers the 90% of cases needed by everyone. So throwing another suggestion in the mix.
>>>>>
>>>>> Taher Alkhateeb
>>>>>
>>>>> ----- Original Message -----
>>>>>
>>>>> From: "Jacques Le Roux" <[hidden email]>
>>>>> To: [hidden email]
>>>>> Sent: Thursday, 28 May, 2015 12:51:13 PM
>>>>> Subject: Re: [DISCUSSION] OFBiz Online Documentation
>>>>>
>>>>> That sounds quite an interesting way Ron.
>>>>> I also believe we should get rid of DocBook in favour of DITTA or maybe even AsciiDoc (the last smart guy) as we already discussed at the bottom of
>>>>> https://issues.apache.org/jira/browse/OFBIZ-4941
>>>>> I also like the idea of separating the documentation from the project (Yippee our 1st sub-project Ron ;) ).
>>>>> Finally, like I said in OFBIZ-4941 I HATE CONFLUENCE, but also, like outlined Sharan (damn can't find the link again), it has a lot of features,
>>>>> notably when it comes to transform formats... and anyway it's our wiki support...
>>>>>
>>>>> Jacques
>>>>>
>>>>> Le 27/05/2015 17:55, Ron Wheeler a écrit :
>>>>>> On 27/05/2015 10:50 AM, Michael Brohl wrote:
>>>>>>> Hi Sharan,
>>>>>>>
>>>>>>> I had not the time to think more about your proposal but I can quickly answer your followup questions, see inline...
>>>>>>>
>>>>>>> Am 27.05.15 um 15:34 schrieb Sharan-F:
>>>>>>>> Hi All
>>>>>>>>
>>>>>>>> I'm still looking for some community feedback on this proposal and approach
>>>>>>>> and now I have a couple of extra questions.
>>>>>>>>
>>>>>>>> To any OFBiz Service providers out there – how do you manage the online help
>>>>>>>> when you install or implement OFBiz? (Is it left as it is, do you remove it
>>>>>>>> or do you create some new online help?)
>>>>>>> In most of our projects, the existing online help is not used at all. The nature of our projects are mostly eCommerce and portal systems with
>>>>>>> another ERP backend like SAP. So the OFBiz backend is either not used at all or only a small part is used. We do trainings with the end users
>>>>>>> then
>>>>>>> and sometimes write some kind of manual which describes the backend use in context to the customer specific processes.
>>>>>>>
>>>>>>> I think there was only one project in the past 13 years which used the online help with partly modified texts.
>>>>>> This is where DITA would be a big help since you could customize the topics that you need to change and leave the rest as is.
>>>>>> I do this with our ADTransform product wherein I write a DITAMAP for a customer that pulls in common topics from the main manual library and
>>>>>> customized topics written for each customer where we are providing the ETVL scripts and want to document the customers particular ETVL workflow.
>>>>>>
>>>>>> This short article introduces a good methodology for handling language customization.
>>>>>> http://www.technical-writer.org/technical-communication/dita-xml-open-toolkit-multilingual-documentation-projects-tutorial-script-linux-bash/
>>>>>> It probably overly detailed for this point in the discussion but I did want to point out how a single overall map can be used to produce
>>>>>> manuals in
>>>>>> different languages that are guaranteed to at least contain the same topics.
>>>>>> It also shows how a multilingual manual would be set up as a project and generated (it shows the linux command line not the IDE as I would
>>>>>> recommend) for those who like to get into the nuts and bolts early.
>>>>>>
>>>>>>
>>>>>>>> To the general community at large - what is the overall feeling about
>>>>>>>> extracting the online help, updating it and then packaging it as a separate
>>>>>>>> project deliverable that can be easily integrated back into OFBiz?
>>>>>>> Mmmhh, we have to make sure that the contents of the online help are in sync with the development and that it is easily editable for project
>>>>>>> specific changes. Then I'm fine with it.
>>>>>> For our ADTransform ETVL product which is a batch process(no on-line help possible or needed) , I use DITA for the manual and edit it in my IDE
>>>>>> and
>>>>>> store it as an SVN (I know that I am old fashioned!) project with my code so I can edit the docs and code together in the IDE.
>>>>>> I produce the manual using Maven within the IDE.
>>>>>>
>>>>>> This makes it easier to keep both in synch by changing whichever file is wrong. Sometimes I write the manual topic first so I capture the spec
>>>>>> before coding it and sometimes I think of good ideas while coding that changes the topic in the manual so it is nice to have both files open in
>>>>>> the
>>>>>> IDE at the same time.
>>>>>>
>>>>>> It does encourage me to write better specs since I have to think out and explain in plain language what the new feature is going to do for the
>>>>>> user
>>>>>> and clearly describe the meaning and possible ranges of values of each of the configuration parameters.
>>>>>>
>>>>>> I also feel better knowing that the effort spent on writing a clear spec will save (or eliminate) documentation effort later. Counters the WISCY
>>>>>> syndrome.
>>>>>>
>>>>>>>> I'm focussing on the approach first. I think that once we have had the
>>>>>>>> discussion about that and reach a concensus can we start discussions around
>>>>>>>> the technology and options to achieve it.
>>>>>>>>
>>>>>>>> Thanks
>>>>>>>> Sharan
>>>>>>>>
>>>>>>> Regards,
>>>>>>>
>>>>>>> Michael Brohl
>>>>>>> ecomify GmbH
>>>>>>> www.ecomify.de
>>>>>>>
>>>>>>
>>>>>
>>>>
>>>
>>
>
>

[Jacques Le Roux]

Le 31/05/2015 14:41, Jacques Le Roux a écrit :
>> It is going to be much better for Integrators that need to produce marketing materials, RFP responses and custom end-user documentation that could
>> be largely composed of topics from the shared OFBiz library of topics simply by defining a map that calls up the topics that you need in the
>> sequence required and applying a format that matches the output requirements.
>> I just don't see how the alternatives that are being discussed can do this and this seems to be a major value that will motivate people to contribute.
>
> You know and use DITA professionally so you have arguments. I have no (at all) experience with AsciiDoc so I can't give good arguments. Could you
> though explain what you mean by  "RFP responses and custom end-user documentation that could be largely composed of topics from the shared OFBiz
> library of topics simply by defining a map that calls up the topics that you need"? Notably what is exactly the "shared OFBiz library of topics"?
Ho, I think you already answered with http://intuillion.com/2015/05/27/how-we-used-dita-to-automate-generation-of-requirements-documents/ I will read
that...

Though still, what is exactly the "shared OFBiz library of topics"?:)

Jacques