Hi All The documentation discussion has come up a few times and I think the last time we talked about some of the topics that are coming up again here.
I agree that some form of version control will help us and means that it can be linked to a release. On the choice of tool, thanks Taher for the brief pros and cons summary of options. Docbook â this has been available in OFBiz for a while, but the implementation we have of it, is not a complete one (i.e. only limited tags work) which means there was something not quite right with the way that we want to use it. I seem to remember it was related to speed of the way things are rendered using it. (Also to be able to use the Webhelp we would have to convert the documents to HTML to display it.) AsciiDoc â I had a brief go with this too and did find it a lot easier to use but a little basic. Dita â Looking at what we want the documentation to achieve, (structured multiple formats, re-use, etc) I think Dita could be a good option that could provide a lot of flexibility and adapt to the project needs. Ron and I had a brief go at setting up a DITA proof of concept. I didn't get very far mainly because of I didnt have any full examples of the documentation I wanted to produce. (Think of it of like having a blank page and someone saying produce the best documentation ever! Where do you start?) BTW - I'm doing some work offline with Craig Parker (some of you might have remembered that he posted a thread a while ago about getting a basic user guide setup). I think if we can at least pull together an example guide and the information that needs to be in it, then it will be easier to analyse and transform that information in a range of documentation settings where it can be re-used (and that strongly ties in with the Dita model.) Thanks Sharan On 2016-08-21 09:40 (+0200), Taher Alkhateeb <slidingfilame...@gmail.com> wrote: > Yeah I really like asciidoc too. I'm making a comparison below specific to > our community for making a choice. Please feel free to correct it or > complete it, it's just a quick idea dump. > > DocBook pros: > - Mature, many books available to read > - Excellent documentation > - Already exists in OFBiz > - Tools and utilities are numerous > > DocBook cons: > - Not modular, more suited for books and articles > - Verbose XML > - Very complex vocabulary with hundreds of tags and countless combinations > > AsciiDoc pros: > - Human friendly > - Minimal learning curve for new users > - Despite simple syntax it has powerful publishing capabilities > - Good documentation > > AsciiDoc cons: > - No books (AFAIK) and online troubleshooting is minimal > - Not modular similar to DocBook > - Tooling support is lacking and few editors support it like vim, emacs, > gedit. > > Dita pros: > - Mature and many books available to read > - Most utilized standard for content authoring and deployed in many large > contexts > - Good documentation (I think DocBook is much better though) > - Modular: this is the single most powerful feature. It allows reusing > content and even parameterized content. The same piece of content could be > used in a tutorial, online help and reference documentation for example. > - Good tooling support (dita-ot) but again nothing beats DocBook in that > area. > > Dita cons > - Verbose XML syntax > - Steeper learning curve due to vocabulary (but nothing compared to DocBook) > - Not very well suited for long documentation (not sure if we have it / > need it) > > I hope I got things right. I think all solutions above are good and I lean > slightly towards dita because of the modularity aspect. > > Taher Alkhateeb > > On Aug 21, 2016 9:03 AM, "Jacques Le Roux" <jacques.le.r...@les7arts.com> > wrote: > > > Le 20/08/2016 à 21:15, Jacques Le Roux a écrit : > > > >> - Provide full documentation through a powerful publishing solution such > >>> as > >>> DocBook or DITA. > >>> > >> > >> +1, but we need to have a consensus with the tool, Paul and I advocated > >> for instance > >> > > Err, forgot "AsciiDoc" in this sentence :/ > > Note: there are AsciiDoc plugins for Eclipse and IntelliJ. With Pandoc you > > can transform almost all formats to another > > > > Interesting contradictory PoV on DITA http://idratherbewriting.com/2 > > 015/01/28/10-reasons-for-moving-away-from-dita/ > > > > Jacques > > > > >
