You are viewing a plain text version of this content. The canonical link for it is here.

Posted to dev@ofbiz.apache.org by Ron Wheeler <rw...@artifact-software.com> on 2015/06/04 17:14:56 UTC

References for DITA as a tool for on-line help

http://www.slideshare.net/abelsp/using-dita-for-online-help
Slideshare has a lot of other presentations on DITA

http://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture
Short with Hello World example

http://en.wikipedia.org/wiki/Online_help
Alternatives for producing on-line help - DocBooks and DITA considered 
together since they are closely related

http://www.ditawriter.com/sample-dita-produced-output/  Has links to 
actual documents produced from DITA sources.

https://www.oasis-open.org/committees/download.php/30122/DHSC_BestPractices_November20_rdr.pdf 
exhaustive article on ways to deliver help authored by DITA tools. It 
shows that an investment in DITA content will always be protected even 
if the OFBiz UI and help delivery technology changes.

Table of Contents
*Introduction to the DITA Help Best Practices Guide*

*Developing DITA-based Help for Existing Help Environments*
-Arbortext Digital Media Publisher
-Eclipse Help
-CSHelp Plug-in
-Eclipse_CSH Plug-in for Dynamic Context-Sensitive Help
-Eclipse Help
-Leximation AIR Help Plug-in
-Microsoft HTMLHelp
-Context-Sensitive Help using the Enhanced HTML (htmlhelp2) Plug-In
-The DITA Open Toolkit HTMLHelp Transform

*Developing Custom DITA-based Help Systems**
*-DHTML Effects in HTML Generated from DITA
-DITA-OT Plug-ins
-HTMLSearch Plug-in
-TOCJS and TOCJSBIS Plug-ins
-Dynamic Rendering of DITA into XHTML
-JavaScript-Based Context Sensitive Help
-WinANT Options Supporting HTML-Based Output
-WinANT Options Supporting Microsoft® HTML Help

*Developing DITA-based Help for Existing Help Authoring Tools**
*-Converting DITA Content to WebHelp using RoboHelp®

There are a lot more articles on using DITA content in On-line help.

The same content is available for other uses.

Ron

-- 
Ron Wheeler
President
Artifact Software Inc
email: rwheeler@artifact-software.com
skype: ronaldmwheeler
phone: 866-970-2435, ext 102

Re: References for DITA as a tool for on-line help

Posted by Jacques Le Roux <ja...@les7arts.com>.

Le 06/06/2015 23:33, Jacques Le Roux a écrit :
> OK DITA seems powerful but not an easy tool to work with (not only because of XML verbosity but also tags and concepts to learn)
> Sincerely the examples in http://fr.wikipedia.org/wiki/Darwin_Information_Typing_Architecture frightens me a bit (and remembers me how verbose is XML)
> We would need to convince the community it's the gith tool for OFBiz documentation... and more...
>
> Also I wonder if we simply don't know Docbook enough to be really able to compare them...
> What would be the cost of moving from DocBook to DITA in OFBiz?
>
> Is http://www.dita-ot.org/ of value?
> Found this by change https://doconv.readthedocs.org/en/latest/features.html
> With http://www.dita-ot.org/2.0/readme/dita2docbook.html this would allow to mix tools (I think we should go that way, but have a tool of reference 
> in OFBiz, still to choose if we don't keep Docbook)
Actually the question is how much these converters are reliable... Only a POC can demonstrate...

Jacques
>
> Jacques
>
> Le 05/06/2015 16:13, Ron Wheeler a écrit :
>> I have found another great reference for planning a DITA project in order to maximize the possibilities for reuse.
>> http://www.stilo.com/article-dita-reuse-conversion-together/
>>
>> It is useful reading if you want reverse engineer some ideas about where the big benefits will come from DITA.
>> For example, it talks about creating a "warehouse for conrefs" where is recommends writing fragments "conrefs" that are included by name.
>> It suggests that these should be used for
>>
>>  * GUI objects, fields, buttons, icons
>>  * Frequently used steps, with step results and info
>>  * All your notes and warnings
>>  * Pre-requisites that are commonly mentioned, like having
>>    administrative privileges
>>  * Boilerplate - legal, copyright, notices,
>>
>> When you think about each of these as a multilingual fragment that can be called in by referencing a key, you can see that this
>> a) reduces translation - translate the key once and every place it is referenced has the translation done
>> b) improves consistency
>> c) makes customization a lot simpler - if you have changed a field label or button label, you only have to change the conref once and it is changed 
>> in your documentation.
>>
>> There is also a discussion on using keys.
>> If we define variables such as version numbers, it makes it easier to ensure that versions (Java, Tomcat, OFBiz, etc.) are consistent everywhere 
>> with a single variable to change.
>> If URLs are keys, you only have to change one key when a web page or file moves.
>> Keys can also be used to select or exclude content which will make it easier for System Integrators to prepare manuals related to different 
>> configurations - include or exclude e-commerce, control industry specific content, etc.
>>
>> It has specific ideas about how to plan and execute a conversion.
>>
>> Ron
>>
>>
>>>>
>>>> ----- Original Message -----
>>>>
>>>> From: "Ron Wheeler" <rw...@artifact-software.com>
>>>> To: "dev" <de...@ofbiz.apache.org>
>>>> Sent: Thursday, 4 June, 2015 6:14:56 PM
>>>> Subject: References for DITA as a tool for on-line help
>>>>
>>>> http://www.slideshare.net/abelsp/using-dita-for-online-help
>>>> Slideshare has a lot of other presentations on DITA
>>>>
>>>> http://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture
>>>> Short with Hello World example
>>>>
>>>> http://en.wikipedia.org/wiki/Online_help
>>>> Alternatives for producing on-line help - DocBooks and DITA considered
>>>> together since they are closely related
>>>>
>>>> http://www.ditawriter.com/sample-dita-produced-output/ Has links to
>>>> actual documents produced from DITA sources.
>>>>
>>>> https://www.oasis-open.org/committees/download.php/30122/DHSC_BestPractices_November20_rdr.pdf
>>>> exhaustive article on ways to deliver help authored by DITA tools. It
>>>> shows that an investment in DITA content will always be protected even
>>>> if the OFBiz UI and help delivery technology changes.
>>>>
>>>> Table of Contents
>>>> *Introduction to the DITA Help Best Practices Guide*
>>>>
>>>> *Developing DITA-based Help for Existing Help Environments*
>>>> -Arbortext Digital Media Publisher
>>>> -Eclipse Help
>>>> -CSHelp Plug-in
>>>> -Eclipse_CSH Plug-in for Dynamic Context-Sensitive Help
>>>> -Eclipse Help
>>>> -Leximation AIR Help Plug-in
>>>> -Microsoft HTMLHelp
>>>> -Context-Sensitive Help using the Enhanced HTML (htmlhelp2) Plug-In
>>>> -The DITA Open Toolkit HTMLHelp Transform
>>>>
>>>> *Developing Custom DITA-based Help Systems**
>>>> *-DHTML Effects in HTML Generated from DITA
>>>> -DITA-OT Plug-ins
>>>> -HTMLSearch Plug-in
>>>> -TOCJS and TOCJSBIS Plug-ins
>>>> -Dynamic Rendering of DITA into XHTML
>>>> -JavaScript-Based Context Sensitive Help
>>>> -WinANT Options Supporting HTML-Based Output
>>>> -WinANT Options Supporting Microsoft® HTML Help
>>>>
>>>> *Developing DITA-based Help for Existing Help Authoring Tools**
>>>> *-Converting DITA Content to WebHelp using RoboHelp®
>>>>
>>>> There are a lot more articles on using DITA content in On-line help.
>>>>
>>>> The same content is available for other uses.
>>>>
>>>> Ron
>>>>
>>>
>>>
>>
>>
>

Re: References for DITA as a tool for on-line help

Posted by Jacques Le Roux <ja...@les7arts.com>.

Hi Sharan,

Though reassured about DITA, I'm in the same mood for now... We have already stuff ready and Tom Burns's work with Webhelp was looking good, surely 
far better than what we render at the moment...

Jacques

Le 08/06/2015 09:06, Sharan Foga a écrit :
> Hi All
>
> I've been looking at the references and yes it does seem quite a powerful tool but I think it might be a bit too much for what we want to achieve 
> for the online help.
>
> One of the references did highlight that if the objective is context sensitive help then DITA may not be the most efficient approach and our online 
> help is all about that.
>
> At the moment I'm looking at what we have in place to see if it can be configured or setup to deliver what we want. Moving from Docbook to DITA is a 
> big change so if Docbook and its webhelp can deliver what we want in less work and effort then I would suggest that we go for that first.
>
> I've opened a Jira here https://issues.apache.org/jira/browse/OFBIZ-6450 to track progress.
>
> Thanks
> Sharan
>
>
> On 07/06/15 20:39, Ron Wheeler wrote:
>> I agree that a lot of the official DITA stuff is pretty intimidating since the early adopters where heavy duty tech writers from IBM who had pretty 
>> serious expert teams involved.
>> It is actually a lot simpler.
>> If you look at my demo and notes, you can see that it is pretty simple to use if you do not need to get into the really obscure stuff.
>> I only use a few of the tags (20?).
>>
>> Ron
>> On 06/06/2015 5:33 PM, Jacques Le Roux wrote:
>>> OK DITA seems powerful but not an easy tool to work with (not only because of XML verbosity but also tags and concepts to learn)
>>> Sincerely the examples in http://fr.wikipedia.org/wiki/Darwin_Information_Typing_Architecture frightens me a bit (and remembers me how verbose is 
>>> XML)
>>> We would need to convince the community it's the gith tool for OFBiz documentation... and more...
>>>
>>> Also I wonder if we simply don't know Docbook enough to be really able to compare them...
>>> What would be the cost of moving from DocBook to DITA in OFBiz?
>>>
>>> Is http://www.dita-ot.org/ of value?
>>> Found this by change https://doconv.readthedocs.org/en/latest/features.html
>>> With http://www.dita-ot.org/2.0/readme/dita2docbook.html this would allow to mix tools (I think we should go that way, but have a tool of 
>>> reference in OFBiz, still to choose if we don't keep Docbook)
>>>
>>> Jacques
>>>
>>> Le 05/06/2015 16:13, Ron Wheeler a écrit :
>>>> I have found another great reference for planning a DITA project in order to maximize the possibilities for reuse.
>>>> http://www.stilo.com/article-dita-reuse-conversion-together/
>>>>
>>>> It is useful reading if you want reverse engineer some ideas about where the big benefits will come from DITA.
>>>> For example, it talks about creating a "warehouse for conrefs" where is recommends writing fragments "conrefs" that are included by name.
>>>> It suggests that these should be used for
>>>>
>>>>  * GUI objects, fields, buttons, icons
>>>>  * Frequently used steps, with step results and info
>>>>  * All your notes and warnings
>>>>  * Pre-requisites that are commonly mentioned, like having
>>>>    administrative privileges
>>>>  * Boilerplate - legal, copyright, notices,
>>>>
>>>> When you think about each of these as a multilingual fragment that can be called in by referencing a key, you can see that this
>>>> a) reduces translation - translate the key once and every place it is referenced has the translation done
>>>> b) improves consistency
>>>> c) makes customization a lot simpler - if you have changed a field label or button label, you only have to change the conref once and it is 
>>>> changed in your documentation.
>>>>
>>>> There is also a discussion on using keys.
>>>> If we define variables such as version numbers, it makes it easier to ensure that versions (Java, Tomcat, OFBiz, etc.) are consistent everywhere 
>>>> with a single variable to change.
>>>> If URLs are keys, you only have to change one key when a web page or file moves.
>>>> Keys can also be used to select or exclude content which will make it easier for System Integrators to prepare manuals related to different 
>>>> configurations - include or exclude e-commerce, control industry specific content, etc.
>>>>
>>>> It has specific ideas about how to plan and execute a conversion.
>>>>
>>>> Ron
>>>>
>>>>
>>>>>>
>>>>>> ----- Original Message -----
>>>>>>
>>>>>> From: "Ron Wheeler" <rw...@artifact-software.com>
>>>>>> To: "dev" <de...@ofbiz.apache.org>
>>>>>> Sent: Thursday, 4 June, 2015 6:14:56 PM
>>>>>> Subject: References for DITA as a tool for on-line help
>>>>>>
>>>>>> http://www.slideshare.net/abelsp/using-dita-for-online-help
>>>>>> Slideshare has a lot of other presentations on DITA
>>>>>>
>>>>>> http://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture
>>>>>> Short with Hello World example
>>>>>>
>>>>>> http://en.wikipedia.org/wiki/Online_help
>>>>>> Alternatives for producing on-line help - DocBooks and DITA considered
>>>>>> together since they are closely related
>>>>>>
>>>>>> http://www.ditawriter.com/sample-dita-produced-output/ Has links to
>>>>>> actual documents produced from DITA sources.
>>>>>>
>>>>>> https://www.oasis-open.org/committees/download.php/30122/DHSC_BestPractices_November20_rdr.pdf
>>>>>> exhaustive article on ways to deliver help authored by DITA tools. It
>>>>>> shows that an investment in DITA content will always be protected even
>>>>>> if the OFBiz UI and help delivery technology changes.
>>>>>>
>>>>>> Table of Contents
>>>>>> *Introduction to the DITA Help Best Practices Guide*
>>>>>>
>>>>>> *Developing DITA-based Help for Existing Help Environments*
>>>>>> -Arbortext Digital Media Publisher
>>>>>> -Eclipse Help
>>>>>> -CSHelp Plug-in
>>>>>> -Eclipse_CSH Plug-in for Dynamic Context-Sensitive Help
>>>>>> -Eclipse Help
>>>>>> -Leximation AIR Help Plug-in
>>>>>> -Microsoft HTMLHelp
>>>>>> -Context-Sensitive Help using the Enhanced HTML (htmlhelp2) Plug-In
>>>>>> -The DITA Open Toolkit HTMLHelp Transform
>>>>>>
>>>>>> *Developing Custom DITA-based Help Systems**
>>>>>> *-DHTML Effects in HTML Generated from DITA
>>>>>> -DITA-OT Plug-ins
>>>>>> -HTMLSearch Plug-in
>>>>>> -TOCJS and TOCJSBIS Plug-ins
>>>>>> -Dynamic Rendering of DITA into XHTML
>>>>>> -JavaScript-Based Context Sensitive Help
>>>>>> -WinANT Options Supporting HTML-Based Output
>>>>>> -WinANT Options Supporting Microsoft® HTML Help
>>>>>>
>>>>>> *Developing DITA-based Help for Existing Help Authoring Tools**
>>>>>> *-Converting DITA Content to WebHelp using RoboHelp®
>>>>>>
>>>>>> There are a lot more articles on using DITA content in On-line help.
>>>>>>
>>>>>> The same content is available for other uses.
>>>>>>
>>>>>> Ron
>>>>>>
>>>>>
>>>>>
>>>>
>>>>
>>>
>>
>>
>
>