ofbiz-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jacques Le Roux <jacques.le.r...@les7arts.com>
Subject Re: References for DITA as a tool for on-line help
Date Sat, 06 Jun 2015 21:39:44 GMT
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
> 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,
>> It has specific ideas about how to plan and execute a conversion.
>> Ron
>>>> ----- Original Message -----
>>>> From: "Ron Wheeler" <rwheeler@artifact-software.com>
>>>> To: "dev" <dev@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

View raw message