On 06/06/2015 5:19 PM, Jacques Le Roux wrote:
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.
I expect that everyone has an IDE that can edit and validate XML. All
the other tools required are free.
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?
Yes but we do have multiple destinations to support - multiple
languages, multiple customizations, multiple brandings.
Topics are likely shared between the same on-line help topic - concepts
shared with different task descriptions.
Eliminate duplication of background material and ensure that there is
only one version of each concept description and that the up to date
description appears in each help screen.
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 would not advise purchasing anything unless you are strictly working
as a technical documentation writter and do not have an IDE and do not
understand XML.
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?
I am sure that other IDE's support XML and auto-completion of XML.
What IDE's are important?
OFBiz is pretty XML intensive so I would be surprised if OFBiz
developers did not use an IDE that can validate XML.
http://when-others-then-null.blogspot.co.uk/2012/12/Validate-XML-against-an-XSD-using-npp.html
talks about using Notepad++ as a validating editor.
If everybody else loves DITA, I would work with it. But I worry that it
will
put many people off.
Possibly but then again OFBiz would be built with Visual Basic if
popularity was the main criteria:-)
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.
--
Ron Wheeler
President
Artifact Software Inc
email: rwhee...@artifact-software.com
skype: ronaldmwheeler
phone: 866-970-2435, ext 102
