On Wednesday, March 14, 2012 10:35:24 AM UTC+11, Lex Trotman wrote: > > On 14 March 2012 09:48, Russell Dickenson wrote: > > Although I have some familiarity with AsciiDoc, having used it for > > some simple documentation, I don't know it well. A discussion came up > > at work recently about the possible advantages of markup languages > > such as AsciiDoc and wiki syntaxes over DocBook, which is what we use > > here at work. > > > > I couldn't think of much at all, I'm afraid. From my POV before > > working with DocBook, the only points which I could think of were: > > > > (1) It's easier to be sure you're working with a valid AsciiDoc > > document because the structural elements don't have to be explicitly > > set - e.g. there's no need for <para> tags etc. Changing a paragraph > > in AsciiDoc into a section is a simple matter of adding the > > appropriate markup (e.g. ========== ). > > (2) AsciiDoc requires only a very low level of entry knowledge; > > (3) AsciiDoc has very few dependencies in converting docs from its > > native format into ePub, HTML, PDF etc. > > > > Are the other points that I am missing? Note that I'm not looking to > > change the method by which I work now since there are many more people > > than myself involved. I also have no interest in starting a flame war. > > I am simply curious to know what advantages others see in AsciiDoc. > > > > I was prompted to write this both by the discussion at work, also the > > posting by O'Reilly about their use of AsciiDoc in producing some > > books. > > > > Hi Russel, > > From my point of view the main advantages of lightweight markup > languages (LML) over any XML based markup are: > > 1. As you say it has a low writer cost of entry, training to use LMLs > is much faster. > > 2. Writers like it better. You are in the position where docbook is > the norm, mostly I was transitioning organisations from word > processors to the joys of single source multiple output format > documenting, and the push-back against XML was significant. > > 2. Most LMLs are less intrusive, more readable so the writer and > reviewers can concentrate more on the content. Though without doing > any scientific studies this seemed to be a real productivity > difference. > > 3. Also don't underestimate the productivity advantages of simply > having less to type, especially where writers are not professional > typists (mine were usually engineers or programmers). And less to > type and simpler to type means less markup errors more content. > > My AUD0.02 >
Add mine too :-) I just transitioned all my project's documentation from docbook to asciidoc (which I then use to generate docbook). As a result I've started getting non-trivial contributions and I no longer dread making edits myself. I couldn't be happier. Docbook is a fantastic format for publishing (particularly when combined with 'publican') but it blows for those doing the writing. -- You received this message because you are subscribed to the Google Groups "asciidoc" group. To view this discussion on the web visit https://groups.google.com/d/msg/asciidoc/-/vz-J3GheA24J. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/asciidoc?hl=en.
