Thanks Taher,
Let's see...
Jacques
Le 06/06/2015 11:19, Taher Alkhateeb a écrit :
Hi Paul,
I am starting to use DITA and really like it. But I can see your point
regarding people being put off. It might be in a sense a bit too powerful for
OFBiz and it takes a while to wrap your head around the concepts like maps,
topics, etc ... I'm on the fence, maybe leaning slightly towards keeping
DocBook, but if a PoC shows how DITA can shine, then why not!
Taher Alkhateeb
----- Original Message -----
From: "Paul Foxworthy" <p...@cohsoft.com.a Pau>
To: dev@ofbiz.apache.org
Sent: Saturday, 6 June, 2015 9:10:28 AM
Subject: Re: Possible Documentation and help solutions - DITA
Sharan-F wrote
I'm a bit unclear about what you are suggesting.
* Is it about replacing the Docbook implementation we currently have
within OFBiz with something else (e.g Asciidoc)?
* Is it about extracting the Docbook content from what we currently
have in OFBiz and then generating it into another format that we
could possibly re-introduce?
* Or is it something else?
Hi Sharan,
My suggestion is much more modest than that. I think there's no need to
replace existing DocBook content, or to totally change the DocBook process
we have.
All I am suggesting is that people consider AsciiDoc as a first step when
authoring help information. If they prefer to work with DocBook directly,
fine. There are tools to transform AsciDoc into DocBook XML, such as
AsciiDoctor (http://asciidoctor.org/), so in effect (correctly written)
AsciiDoc *is* DocBook.
I'll repeat the reasons why I like AsciiDoc. It's more human-readable than
XML. You can write your documentation in any text editor. Both of these are
important. In contrast, requiring XML and some more specialised tool is a
barrier to entry, so less people could and would participate in documenting
OFBiz.
When I last looked into DITA quite a few years ago, it seemed to be a
heavyweight thing that only made sense if you wanted multiple destinations
and were willing to invest in proprietary tools like Framemaker, Oxygen or
Arbortext. I am perfectly willing to believe that DITA is more "complete"
than DocBook, and would allow "better" documentation, if only anyone was
willing to invest the time, trouble and money to be able to use it.
I'm pleased to hear there's now DITA support for Eclipse. Eclipse is not my
favourite IDE, but I could be persuaded to use it. How much better would it
be to say to potential contributors that they can use their favourite IDE or
text editor, whatever that is?
If everybody else loves DITA, I would work with it. But I worry that it will
put many people off.
Thanks
Paul Foxworthy
-----
