“Writing is hard.”
That’s what experience has conditioned us to believe.
But, we can’t just avoid it, especially in the tech industry. We must write. Even the most brilliant software is useless without good documentation. If the users fail, so does the project.
Unless your UI discoverability is really good, saying “the feature isn’t documented” is the same as saying “the product can’t do it.”
In other words,
Live and die by documentation.
Then why, oh why, do we make it more difficult by burying the content in XML schemas like DocBook, allowing complex word processors to distract us or wasting time battling with finicky WYSIWYG editors?
Imagine if writing documentation was as simple as writing an email.
It can be.
That’s the idea behind lightweight markup languages such as AsciiDoc. They offer a plain-text syntax, embellished with subtle, yet intuitive markup, that’s designed for humans to read, write and edit in raw form. The natural feel of the syntax keeps you focused on the content. Best of all, the plain text can quickly and easily be translated into output formats such as HTML5 for presentation.
AsciiDoc belongs to the family of lightweight markup languages, the most renowned of which is Markdown. AsciiDoc stands out from this group because it supports all the structural elements necessary for drafting articles, technical manuals, books, presentations and prose. In fact, it’s capable of meeting even the most advanced publishing requirements and technical semantics.
Lightweight Markup languages are designed to enable humans to write documents, and for other humans to be able to read them, as is, in raw form.
In conclusion:
Use AsciiDoc for document markup. Really. It’s actually readable by humans, easier to parse and way more flexible than XML.
- Appendix
-
For a more indepth wording, see AsciiDoctors' Article on "What is AsciiDoc? Why do we need it?".
AsciiDoc is actually two things:
-
A mature (introduced 2002), plain-text writing format for authoring notes, articles, documentation, books, ebooks, web pages, slide decks, blog posts, man pages and more.
-
A text processor and toolchain for translating AsciiDoc documents into various formats (called backends), including HTML, DocBook, PDF and ePub.
There are two implementations of the AsciiDoc processor.
-
The original processor, named AsciiDoc, is written in Python.
-
A more modern implementation, named Asciidoctor, provides a compliant and substantially faster implementation of the AsciiDoc processor written in Ruby. This implementation can also be run on the JVM (with AsciidoctorJ) or using JavaScript (with Asciidoctor.js).
The Asciidoctor project now maintains the official definition of the AsciiDoc syntax and delivers ongoing development, as officially stated on AsciiDocs' Website and Github.
AsciiDoc itself is not a publishing format. It’s more like a shorthand. That’s where an AsciiDoc processor comes in. This Project uses AsciiDoctor as the processor.
Since AsciiDoc was and is not published as is, the processing step provided/provides an opportunity to augment the document by expanding shorthand codes, layering in integrations (e.G. to generate various Diagrams in-line), and applying a pleasant visual style. That augmentation is a large part of what Asciidoctor does.
-
For an introduction, see AsciiDoctors' Landing Page.
-
For a Quick Reference of AsciiDoc’s Syntax, see AsciiDoctors' Quick Reference Guide.
-
For a gentle but in-depth Introduction to AsciiDoc, see AsciiDoctors' AsciiDoc Writers Guide.