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" <rwhee...@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
