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" <jacques.le.r...@les7arts.com>
To: user@ofbiz.apache.org
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
