Le 06/06/2015 08:10, Paul Foxworthy a écrit :
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.
That's exactly the point indeed, thanks to stress that Paul.
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
This seems to answer to my question just asked to Ron on the user ML. So you think Docbook (more aimed to create book when DITA is more of online help
kind, I read) or AsciiDoc are not able to OOTB deliver in this way?
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.
That's the point we need to clarify...
Jacques
Thanks
Paul Foxworthy
-----
--
Coherent Software Australia Pty Ltd
http://www.coherentsoftware.com.au/
Bonsai ERP, the all-inclusive ERP system
http://www.bonsaierp.com.au/
--
View this message in context:
http://ofbiz.135035.n4.nabble.com/Possible-Documentation-and-help-solutions-DITA-tp4669377p4669576.html
Sent from the OFBiz - Dev mailing list archive at Nabble.com.
