You are viewing a plain text version of this content. The canonical link for it is here.
Posted to user@ofbiz.apache.org by Sharan-F <sh...@gmail.com> on 2015/05/21 18:45:11 UTC
[DISCUSSION] OFBiz Online Documentation
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.
Re: [DISCUSSION] OFBiz Online Documentation
Posted by Todd Thorner <tt...@infotinuum.com>.
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.
>
Re: [DISCUSSION] OFBiz Online Documentation
Posted by Pierre Smits <pi...@gmail.com>.
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 <
jacques.le.roux@les7arts.com> 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" <ja...@les7arts.com>
>>>> To: user@ofbiz.apache.org
>>>> 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
>>>>>>
>>>>>>
>>>>>
>>>>
>>>
>>
Re: [DISCUSSION] OFBiz Online Documentation
Posted by Jacques Le Roux <ja...@les7arts.com>.
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.
>>>
>>>
>>
>
>
Re: [DISCUSSION] OFBiz Online Documentation
Posted by Ron Wheeler <rw...@artifact-software.com>.
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: rwheeler@artifact-software.com
skype: ronaldmwheeler
phone: 866-970-2435, ext 102
Re: [DISCUSSION] OFBiz Online Documentation
Posted by Jacques Le Roux <ja...@les7arts.com>.
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.
>
>
Re: [DISCUSSION] OFBiz Online Documentation
Posted by Ron Wheeler <rw...@artifact-software.com>.
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: rwheeler@artifact-software.com
skype: ronaldmwheeler
phone: 866-970-2435, ext 102
Re: [DISCUSSION] OFBiz Online Documentation
Posted by Jacques Le Roux <ja...@les7arts.com>.
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
Re: [DISCUSSION] OFBiz Online Documentation
Posted by Jacques Le Roux <ja...@les7arts.com>.
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" <ja...@les7arts.com>
>>>>> To: user@ofbiz.apache.org
>>>>> 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
>>>>>>>
>>>>>>
>>>>>
>>>>
>>>
>>
>
>
Re: [DISCUSSION] OFBiz Online Documentation
Posted by Ron Wheeler <rw...@artifact-software.com>.
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" <ja...@les7arts.com>
>>>> To: user@ofbiz.apache.org
>>>> 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: rwheeler@artifact-software.com
skype: ronaldmwheeler
phone: 866-970-2435, ext 102
Re: [DISCUSSION] OFBiz Online Documentation
Posted by Todd Thorner <tt...@infotinuum.com>.
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.
>>
>>
>
>
Re: [DISCUSSION] OFBiz Online Documentation
Posted by Michael Brohl <mi...@ecomify.de>.
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.
>
>
Re: [DISCUSSION] OFBiz Online Documentation
Posted by Todd Thorner <tt...@infotinuum.com>.
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" <ja...@les7arts.com>
>>>> To: user@ofbiz.apache.org
>>>> 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
>>>>>>
>>>>>
>>>>
>>>
>>
Re: [DISCUSSION] OFBiz Online Documentation
Posted by Jacques Le Roux <ja...@les7arts.com>.
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" <ja...@les7arts.com>
>>> To: user@ofbiz.apache.org
>>> 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
>>>>>
>>>>
>>>
>>
>
Re: [DISCUSSION] OFBiz Online Documentation
Posted by Jacques Le Roux <ja...@les7arts.com>.
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" <ja...@les7arts.com>
>> To: user@ofbiz.apache.org
>> 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
>>>>
>>>
>>
>
Re: [DISCUSSION] OFBiz Online Documentation
Posted by Jacques Le Roux <ja...@les7arts.com>.
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" <ja...@les7arts.com>
> To: user@ofbiz.apache.org
> 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
>>>
>>
>
Re: [DISCUSSION] OFBiz Online Documentation
Posted by Taher Alkhateeb <sl...@gmail.com>.
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" <ja...@les7arts.com>
To: user@ofbiz.apache.org
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
>>
>
>
Re: [DISCUSSION] OFBiz Online Documentation
Posted by Jacques Le Roux <ja...@les7arts.com>.
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
>>
>
>
Re: [DISCUSSION] OFBiz Online Documentation
Posted by Ron Wheeler <rw...@artifact-software.com>.
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: rwheeler@artifact-software.com
skype: ronaldmwheeler
phone: 866-970-2435, ext 102
Re: [DISCUSSION] OFBiz Online Documentation
Posted by Michael Brohl <mi...@ecomify.de>.
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
Re: [DISCUSSION] OFBiz Online Documentation
Posted by Jacques Le Roux <ja...@les7arts.com>.
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 <ja...@les7arts.com> 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 <sh...@gmail.com> 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.
>>
>
Re: [DISCUSSION] OFBiz Online Documentation
Posted by Jacques Le Roux <ja...@les7arts.com>.
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 <ja...@les7arts.com> 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 <sh...@gmail.com> 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.
>
Re: [DISCUSSION] OFBiz Online Documentation
Posted by Paul Mandeltort <pa...@marcospec.com>.
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 <ja...@les7arts.com> 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 <sh...@gmail.com> 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.
>>
Re: [DISCUSSION] OFBiz Online Documentation
Posted by Jacques Le Roux <ja...@les7arts.com>.
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 <sh...@gmail.com> 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.
>
Re: [DISCUSSION] OFBiz Online Documentation
Posted by Paul Mandeltort <pa...@marcospec.com>.
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 <sh...@gmail.com> 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.
Re: [DISCUSSION] OFBiz Online Documentation
Posted by Sharan-F <sh...@gmail.com>.
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.