[DISCUSSION] OFBiz Online Documentation

[Ron Wheeler]

On 31/05/2015 8:42 AM, Jacques Le Roux wrote:

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

Short answer.
The manual or help system git project would have topics such as
*Concept Topics*
- goal of OFBiz eCommerce  - OFBiz_eCommerce_goal.dita
- OFBiz eCommerce overview - OFBiz_eCommerce_overview.dita
- OFBiz eComerce Benefits - OFBiz_eCommerce_benefits.dita
- OFBiz eCommerce Features - OFBiz_eCommerce_features.dita
- OFBiz ecommerce and Paypal - OFBiz_eCommerce_with_Paypal.dita
- OFBiz eCommerce and Google Wallet -
OFBiz_eCommerce_with_Google_Wallet.dita
- Shopping cart Overview
*Task Topics*
- configuring PayPay in OfBiz - Configuring_OFBiz_eCommerce_with_Paypal.dita
- configuring Google Wallet in OFBiz -
Configuring_OFBiz_eCommerce_with_Google_Wallet.dita
- Shopping Cart payment process - Paying_with_eCommerce
   - with Paypal - Paying_with_eCommerce_through_PayPal
   - with Google Wallet - Paying with eCommerce_through_Google_Wallet


There would be hundreds of topics when you start to breakdown all of the
things that one might want to say about OFBiz in help and the web site.

If you were writing a marketing brochure for your company, you would
create a ditamap that included  "OFBiz_eCommerce_overview.dita" and
perhaps "OFBiz_eCommerce_benefits.dita" or
"OFBiz_eCommerce_features.dita". The map would include references to
other similar pieces from the library.
You would have your company profile, perhaps some topics targeted at the
industry that you are approaching, and a topic that has your references.
This DITAmap would be processed through your customized DITA-OT process
to add your branding and format it as a brochure.

If you were responding to an RFP that asked about Paypal, you might
select  "OFBiz_eCommerce_overview.dita" and
"OFBiz_eCommerce_with_Paypal.dita" with
"Paying_with_eCommerce_through_PayPal" if the RFP asked for details.
You would have your own topics about legal, support, references,
industry experience, etc that you would include in the RFP respose.


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

[Jacques Le Roux]

Thanks Ron,

That's interesting but seems quite a lot of work, not sure the community will commit to provide it... Let's see...

I also wonder if this could not be done with DocBook or AsciiDoc. What is specific to DITA that 2 other systems have not to do the same?

Thanks

Jacques


Le 31/05/2015 15:59, Ron Wheeler a écrit :

> On 31/05/2015 8:42 AM, Jacques Le Roux wrote:
>> 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
>>
> Short answer.
> The manual or help system git project would have topics such as
> *Concept Topics*
> - goal of OFBiz eCommerce  - OFBiz_eCommerce_goal.dita
> - OFBiz eCommerce overview - OFBiz_eCommerce_overview.dita
> - OFBiz eComerce Benefits - OFBiz_eCommerce_benefits.dita
> - OFBiz eCommerce Features - OFBiz_eCommerce_features.dita
> - OFBiz ecommerce and Paypal - OFBiz_eCommerce_with_Paypal.dita
> - OFBiz eCommerce and Google Wallet - OFBiz_eCommerce_with_Google_Wallet.dita
> - Shopping cart Overview
> *Task Topics*
> - configuring PayPay in OfBiz - Configuring_OFBiz_eCommerce_with_Paypal.dita
> - configuring Google Wallet in OFBiz - Configuring_OFBiz_eCommerce_with_Google_Wallet.dita
> - Shopping Cart payment process - Paying_with_eCommerce
>   - with Paypal - Paying_with_eCommerce_through_PayPal
>   - with Google Wallet - Paying with eCommerce_through_Google_Wallet
>
>
> There would be hundreds of topics when you start to breakdown all of the things that one might want to say about OFBiz in help and the web site.
>
> If you were writing a marketing brochure for your company, you would create a ditamap that included "OFBiz_eCommerce_overview.dita" and perhaps
> "OFBiz_eCommerce_benefits.dita" or "OFBiz_eCommerce_features.dita". The map would include references to other similar pieces from the library.
> You would have your company profile, perhaps some topics targeted at the industry that you are approaching, and a topic that has your references.
> This DITAmap would be processed through your customized DITA-OT process to add your branding and format it as a brochure.
>
> If you were responding to an RFP that asked about Paypal, you might select  "OFBiz_eCommerce_overview.dita" and "OFBiz_eCommerce_with_Paypal.dita"
> with "Paying_with_eCommerce_through_PayPal" if the RFP asked for details.
> You would have your own topics about legal, support, references, industry experience, etc that you would include in the RFP respose.
>
>

[Ron Wheeler]

http://thecontentwrangler.com/2008/04/11/choosing_an_xml_schema_docbook_or_dita/

I am feel that AsciiDoc is too much like a wiki tool
- no validation so you have to read the output to know if you are right.
- IDEs used by most developers can auto-validate XML and provide code
completion so DITA is going to be easy for developers to use - more
chance that docs match code.
- too much formatting embedded in the AsciiDoc markup so it is going to
be harder to reuse and rebrand for different System Integrators or customers
- No translation support in AsciiDoc.
- harder to include and exclude topics in AsciiDoc to make sure that you
can use the dynamic configuration of help to match components selected
or activated in a particular installation.
- hard to reuse AsciiDoc in other outputs such as proposals, contracts,
custom specifications, brochures, web sites, etc.

Converting DocBook to DITA is not a big deal except that there will
probably be a desire to update and restructure the current DocBook to
make it better and more modular.


Ron


On 06/06/2015 5:14 PM, Jacques Le Roux wrote:

> Thanks Ron,
>
> That's interesting but seems quite a lot of work, not sure the
> community will commit to provide it... Let's see...
>
> I also wonder if this could not be done with DocBook or AsciiDoc. What
> is specific to DITA that 2 other systems have not to do the same?
>
> Thanks
>
> Jacques
>
>
> Le 31/05/2015 15:59, Ron Wheeler a écrit :
>> On 31/05/2015 8:42 AM, Jacques Le Roux wrote:
>>> 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
>>>
>> Short answer.
>> The manual or help system git project would have topics such as
>> *Concept Topics*
>> - goal of OFBiz eCommerce  - OFBiz_eCommerce_goal.dita
>> - OFBiz eCommerce overview - OFBiz_eCommerce_overview.dita
>> - OFBiz eComerce Benefits - OFBiz_eCommerce_benefits.dita
>> - OFBiz eCommerce Features - OFBiz_eCommerce_features.dita
>> - OFBiz ecommerce and Paypal - OFBiz_eCommerce_with_Paypal.dita
>> - OFBiz eCommerce and Google Wallet -
>> OFBiz_eCommerce_with_Google_Wallet.dita
>> - Shopping cart Overview
>> *Task Topics*
>> - configuring PayPay in OfBiz -
>> Configuring_OFBiz_eCommerce_with_Paypal.dita
>> - configuring Google Wallet in OFBiz -
>> Configuring_OFBiz_eCommerce_with_Google_Wallet.dita
>> - Shopping Cart payment process - Paying_with_eCommerce
>>   - with Paypal - Paying_with_eCommerce_through_PayPal
>>   - with Google Wallet - Paying with eCommerce_through_Google_Wallet
>>
>>
>> There would be hundreds of topics when you start to breakdown all of
>> the things that one might want to say about OFBiz in help and the web
>> site.
>>
>> If you were writing a marketing brochure for your company, you would
>> create a ditamap that included "OFBiz_eCommerce_overview.dita" and
>> perhaps "OFBiz_eCommerce_benefits.dita" or
>> "OFBiz_eCommerce_features.dita". The map would include references to
>> other similar pieces from the library.
>> You would have your company profile, perhaps some topics targeted at
>> the industry that you are approaching, and a topic that has your
>> references.
>> This DITAmap would be processed through your customized DITA-OT
>> process to add your branding and format it as a brochure.
>>
>> If you were responding to an RFP that asked about Paypal, you might
>> select  "OFBiz_eCommerce_overview.dita" and
>> "OFBiz_eCommerce_with_Paypal.dita" with
>> "Paying_with_eCommerce_through_PayPal" if the RFP asked for details.
>> You would have your own topics about legal, support, references,
>> industry experience, etc that you would include in the RFP respose.
>>
>>
>

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

[Jacques Le Roux]

Thanks Ron,

It's clearer now. With Taher's document about DITA tags, I'm more inclined about it now.

Looking forward for your POC.

Jacques

Le 07/06/2015 20:21, Ron Wheeler a écrit :

> http://thecontentwrangler.com/2008/04/11/choosing_an_xml_schema_docbook_or_dita/
>
> I am feel that AsciiDoc is too much like a wiki tool
> - no validation so you have to read the output to know if you are right.
> - IDEs used by most developers can auto-validate XML and provide code completion so DITA is going to be easy for developers to use - more chance
> that docs match code.
> - too much formatting embedded in the AsciiDoc markup so it is going to be harder to reuse and rebrand for different System Integrators or customers
> - No translation support in AsciiDoc.
> - harder to include and exclude topics in AsciiDoc to make sure that you can use the dynamic configuration of help to match components selected or
> activated in a particular installation.
> - hard to reuse AsciiDoc in other outputs such as proposals, contracts, custom specifications, brochures, web sites, etc.
>
> Converting DocBook to DITA is not a big deal except that there will probably be a desire to update and restructure the current DocBook to make it
> better and more modular.
>
>
> Ron
>
>
> On 06/06/2015 5:14 PM, Jacques Le Roux wrote:
>> Thanks Ron,
>>
>> That's interesting but seems quite a lot of work, not sure the community will commit to provide it... Let's see...
>>
>> I also wonder if this could not be done with DocBook or AsciiDoc. What is specific to DITA that 2 other systems have not to do the same?
>>
>> Thanks
>>
>> Jacques
>>
>>
>> Le 31/05/2015 15:59, Ron Wheeler a écrit :
>>> On 31/05/2015 8:42 AM, Jacques Le Roux wrote:
>>>> 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
>>>>
>>> Short answer.
>>> The manual or help system git project would have topics such as
>>> *Concept Topics*
>>> - goal of OFBiz eCommerce  - OFBiz_eCommerce_goal.dita
>>> - OFBiz eCommerce overview - OFBiz_eCommerce_overview.dita
>>> - OFBiz eComerce Benefits - OFBiz_eCommerce_benefits.dita
>>> - OFBiz eCommerce Features - OFBiz_eCommerce_features.dita
>>> - OFBiz ecommerce and Paypal - OFBiz_eCommerce_with_Paypal.dita
>>> - OFBiz eCommerce and Google Wallet - OFBiz_eCommerce_with_Google_Wallet.dita
>>> - Shopping cart Overview
>>> *Task Topics*
>>> - configuring PayPay in OfBiz - Configuring_OFBiz_eCommerce_with_Paypal.dita
>>> - configuring Google Wallet in OFBiz - Configuring_OFBiz_eCommerce_with_Google_Wallet.dita
>>> - Shopping Cart payment process - Paying_with_eCommerce
>>>   - with Paypal - Paying_with_eCommerce_through_PayPal
>>>   - with Google Wallet - Paying with eCommerce_through_Google_Wallet
>>>
>>>
>>> There would be hundreds of topics when you start to breakdown all of the things that one might want to say about OFBiz in help and the web site.
>>>
>>> If you were writing a marketing brochure for your company, you would create a ditamap that included "OFBiz_eCommerce_overview.dita" and perhaps
>>> "OFBiz_eCommerce_benefits.dita" or "OFBiz_eCommerce_features.dita". The map would include references to other similar pieces from the library.
>>> You would have your company profile, perhaps some topics targeted at the industry that you are approaching, and a topic that has your references.
>>> This DITAmap would be processed through your customized DITA-OT process to add your branding and format it as a brochure.
>>>
>>> If you were responding to an RFP that asked about Paypal, you might select  "OFBiz_eCommerce_overview.dita" and "OFBiz_eCommerce_with_Paypal.dita"
>>> with "Paying_with_eCommerce_through_PayPal" if the RFP asked for details.
>>> You would have your own topics about legal, support, references, industry experience, etc that you would include in the RFP respose.
>>>
>>>
>>
>
>

[Jacques Le Roux]

That's good, but I prefer to refer to a more generalised page with other "Examples of HIGs" http://en.wikipedia.org/wiki/Human_interface_guidelines
Anyone can pick is preferred...

Jacques

Le 28/05/2015 14:58, Paul Mandeltort a écrit :

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

[Jacques Le Roux]

Le 08/06/2015 13:29, Jacques Le Roux a écrit :
> That's good, but I prefer to refer to a more generalised page with other "Examples of HIGs" http://en.wikipedia.org/wiki/Human_interface_guidelines
> Anyone can pick is preferred...

I meant "Anyone can pick her/his preferred... " :)

Jacques

>
> Jacques
>
> Le 28/05/2015 14:58, Paul Mandeltort a écrit :
>> 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.
>>
>