12 Sep ascii-doc-tool
AsciiDoc - A Simple Documentation Authoring Tool
- Tech Writer's Tribe
AsciiDoc is a markup language that helps technical writers author in plain text without having to bother about the challenges of complex formatting. While using an AsciiDoc editor lets you focus completely on authoring, the output helps it compete with many popular technical documentation tools.
Technical Publications teams who prefer to have complete control over technical documentation from scratch to publication on the website and prefer the Documentation-as-code approach cherish the usage of AsciiDoc more often.
In simple words, it is a text document editor for:
- Technical Documentation
- Articles
- EBooks
- Books (Print)
- Web Pages
AsciiDoc vs Markdown
Most of the authors who have used both AsciiDoc and Markdown, praise AsciiDoc for the ease of learning, simple usage and better formatting features. Unlike Markdown, this Markup application (AsciiDoc) has more options for formatting and creating desired structure for the documents.
Author, Collaborate and Publish to Website
AsciiDoc editors can be downloaded free of cost, unless you are looking out to spend money and buy premium features. Using easy-to-remember short-codes, even a beginner can author without much guidance.
Collaboration for reviews is one of the key benefits of the documentation-as-code process. AsciiDoc not only allows you to easily integrate with GitHub and BitBucket, but is also popular enough to be available in GitHub as a language for creating documents if you prefer working directly on GitHub.
Publishing to your websites requires a sync-up with a static-site-generator. Based on your requirement, you can pick any of the popular tools. For example, Jekyll, Hugo, and Sphinx.
The benefits increase further as AsciiDoc allows integrations with many plug-ins. The options for output are also more when using AsciiDoc files.
Structure of an AsciiDoc Document
A document can be divided into the following two parts:
- Document Attributes (Header section of the document): Helps you define the rules and formats applicable to the whole document.
- Sections (Body part): Author the document using multiple short-codes for formatting.
From the same source file, you can publish numbered TOC (for PDF output) and TOC without numbers (For HTML output)
The sections can have general formatting as used in any other tools for:
- Chapter
- Sub-chapters
- Paragraph
- In-line formatting: Bold, Italics, Underline, Strikethrough, Mono
- Code blocks
- List numbers or bullets including mixed or nested lists up to multiple levels
- Information Types: Notes, Important and Caution with images
- Graphics/Videos with defined size and alignment
- Tables
- Hyperlinks and cross-references
- Mail to macros
- Several other formatting styles
Additional Formatting for Technical Writers
- Create a complete FAQ guide or section without having to bother about alignment and numbering.
- Use Description List to describe fields within steps with desired alignment without breaking the sequence of lists.
- Special Characters: Superscript (^), Subscript (1st)
- Textual Symbols: Copyright (C), Trademark (TM), Registered (R)
- Single or double arrows in both the directions
- List with a title
Get Started
Download an AsciiDoc editor as per your OS and start creating your document. To learn, you can use the references or join a workshop.
Note: Tech Writer’s Tribe conducts workshops on using AsciiDoc with BitBucket or GitHub.
Some AsciiDoc Editors
- Mac OS: TextMate
- Linux OS: GEdit
- Windows OS: Notepad++
- PyCharm
Things to Remember
- 2002: Stuart Rackham created this tool.
- Language: Written in Python to convert plain text into multiple documentation formats.
- Operating System: Cross Platform
- 2013: Asciidoctor, a Ruby implementation, was released and is in use by GitHub and GitLab.
No Comments