One of the things that concerns me about AsciiDoc is that some
formatting is mixed in with content.
This makes reuse problematic.
I am not sure that IDE's can validate AsciiDoc documents or provide
"code" assist/autocompletion which is possible for IDE's such as Eclipse
with DITA.
I am not sure that translation support exists for AsciiDoc as fully as
it does for DITA.
I find the wide variety of characters used to identify markup to be
disconcerting to someone who is used to XML tags.
In DITA, if it is an XML tag it is DITA anything else is not.
In AsciiDoc many different characters are used to signal a ASCIIDoc
notation and some depend on position in the text ("." in column 1)
I maintain websites in MediaWiki, Confluence and Wordpress.
I would still go with DITA for documentation because of its simplicity
and rigour in authoring and flexibility in output.
It is going to be much better for Integrators that need to produce
marketing materials, RFP responses and custom end-user documentation
that could be largely composed of topics from the shared OFBiz library
of topics simply by defining a map that calls up the topics that you
need in the sequence required and applying a format that matches the
output requirements.
I just don't see how the alternatives that are being discussed can do
this and this seems to be a major value that will motivate people to
contribute.
Ron
On 28/05/2015 7:44 AM, Jacques Le Roux wrote:
And finally:
Read theStandardization section at http://en.wikipedia.org/wiki/Markdown
Also this one is maybe a bit biased (done by Dan Allen who supports
AsciiDOc) but still an interesting comparison:
https://gist.github.com/mojavelinux/5870367
check
Asciidoc
https://gist.githubusercontent.com/mojavelinux/5870367/raw/014804bf061baad6983ade6878484b9c0931da5b/gfm-vs-asciidoc.asciidoc
vs
Markdown
https://github.github.com/github-flavored-markdown/sample_content.html
Jacques
Le 28/05/2015 13:24, Jacques Le Roux a écrit :
Another interesting opinion: http://www.neveruntilnow.com/asciidoctor/
Jacques
Le 28/05/2015 13:19, Jacques Le Roux a écrit :
I'm still undecided on this, but I feel AsciiDoc is "slowly" gaining
interest see
http://www.artima.com/forums/flat.jsp?forum=106&thread=361787 It's
the same spirit than Json againt XML...Though Markdown is not XML,
but Dita is. Also AsciiDoc offers a lot of export possibilities, see
http://en.wikipedia.org/wiki/Comparison_of_document_markup_languages
Anyway we will need a community consensus...
Jacques
Le 28/05/2015 12:29, Taher Alkhateeb a écrit :
Hi Jacques and all,
If you want a simple documentation language then markdown comes to
mind. It is simple, beautiful, mature and well supported in terms
of tools and probably covers the 90% of cases needed by everyone.
So throwing another suggestion in the mix.
Taher Alkhateeb
----- Original Message -----
From: "Jacques Le Roux" <[email protected]>
To: [email protected]
Sent: Thursday, 28 May, 2015 12:51:13 PM
Subject: Re: [DISCUSSION] OFBiz Online Documentation
That sounds quite an interesting way Ron.
I also believe we should get rid of DocBook in favour of DITTA or
maybe even AsciiDoc (the last smart guy) as we already discussed at
the bottom of
https://issues.apache.org/jira/browse/OFBIZ-4941
I also like the idea of separating the documentation from the
project (Yippee our 1st sub-project Ron ;) ).
Finally, like I said in OFBIZ-4941 I HATE CONFLUENCE, but also,
like outlined Sharan (damn can't find the link again), it has a lot
of features,
notably when it comes to transform formats... and anyway it's our
wiki support...
Jacques
Le 27/05/2015 17:55, Ron Wheeler a écrit :
On 27/05/2015 10:50 AM, Michael Brohl wrote:
Hi Sharan,
I had not the time to think more about your proposal but I can
quickly answer your followup questions, see inline...
Am 27.05.15 um 15:34 schrieb Sharan-F:
Hi All
I'm still looking for some community feedback on this proposal
and approach
and now I have a couple of extra questions.
To any OFBiz Service providers out there – how do you manage the
online help
when you install or implement OFBiz? (Is it left as it is, do
you remove it
or do you create some new online help?)
In most of our projects, the existing online help is not used at
all. The nature of our projects are mostly eCommerce and portal
systems with
another ERP backend like SAP. So the OFBiz backend is either not
used at all or only a small part is used. We do trainings with
the end users then
and sometimes write some kind of manual which describes the
backend use in context to the customer specific processes.
I think there was only one project in the past 13 years which
used the online help with partly modified texts.
This is where DITA would be a big help since you could customize
the topics that you need to change and leave the rest as is.
I do this with our ADTransform product wherein I write a DITAMAP
for a customer that pulls in common topics from the main manual
library and
customized topics written for each customer where we are providing
the ETVL scripts and want to document the customers particular
ETVL workflow.
This short article introduces a good methodology for handling
language customization.
http://www.technical-writer.org/technical-communication/dita-xml-open-toolkit-multilingual-documentation-projects-tutorial-script-linux-bash/
It probably overly detailed for this point in the discussion but I
did want to point out how a single overall map can be used to
produce manuals in
different languages that are guaranteed to at least contain the
same topics.
It also shows how a multilingual manual would be set up as a
project and generated (it shows the linux command line not the IDE
as I would
recommend) for those who like to get into the nuts and bolts early.
To the general community at large - what is the overall feeling
about
extracting the online help, updating it and then packaging it as
a separate
project deliverable that can be easily integrated back into OFBiz?
Mmmhh, we have to make sure that the contents of the online help
are in sync with the development and that it is easily editable
for project
specific changes. Then I'm fine with it.
For our ADTransform ETVL product which is a batch process(no
on-line help possible or needed) , I use DITA for the manual and
edit it in my IDE and
store it as an SVN (I know that I am old fashioned!) project with
my code so I can edit the docs and code together in the IDE.
I produce the manual using Maven within the IDE.
This makes it easier to keep both in synch by changing whichever
file is wrong. Sometimes I write the manual topic first so I
capture the spec
before coding it and sometimes I think of good ideas while coding
that changes the topic in the manual so it is nice to have both
files open in the
IDE at the same time.
It does encourage me to write better specs since I have to think
out and explain in plain language what the new feature is going to
do for the user
and clearly describe the meaning and possible ranges of values of
each of the configuration parameters.
I also feel better knowing that the effort spent on writing a
clear spec will save (or eliminate) documentation effort later.
Counters the WISCY
syndrome.
I'm focussing on the approach first. I think that once we have
had the
discussion about that and reach a concensus can we start
discussions around
the technology and options to achieve it.
Thanks
Sharan
Regards,
Michael Brohl
ecomify GmbH
www.ecomify.de
--
Ron Wheeler
President
Artifact Software Inc
email: [email protected]
skype: ronaldmwheeler
phone: 866-970-2435, ext 102
