Skip to main content

Introduction to Asciidoc

Creating technical documentation, as you know, is one of the most essential tasks of Technical Writers. Documentation is integral in the Software development process, for developers as developer documentation and users as user documentation.

For developers, documentation serves as a repository of valuable knowledge that helps in understanding how the system works. It also encourages knowledge sharing amongst developers.

For users, on the other hand, effectively written documentation can help improve the user’s experience with the product. For example, technical documents such as how-to guides, FAQs, and Troubleshooting guides help the user understand a particular product better.

Now that you understand the importance of documentation in the software development process and how its creation is an essential task for Technical Writers, you will learn an important markup language used by technical writers called AsciiDoc.

Course Overview​

This course covers the following topics:

  • Getting started with AsciiDoc using Antora
  • Writing in AsciiDoc
  • Different building blocks available in AsciiDoc
  • Converting your AsciiDoc documents

So let’s get right into it.

What is AsciiDoc?​

You may wonder if there’s a relationship between the popular ASCII Characters and AsciiDoc, in a way, there is but it is important to note that the “Ascii” in AsciiDoc does not refer to the characters that define the language syntax.

Although, ASCII characters can be used to express an AsciiDoc document, any character range in Unicode (UTF-8) is employed in expressing the full content of an AsciiDoc document which may include titles, paragraphs, etc.

AsciiDoc is a simple and plain markup language for writing technical documents or content. The language is written in a human-readable, plain text format. The syntax is easy to use and understand as it relies on an already-established, plain text rule for marking up and text structuring.

AsciiDoc has the ability to produce document output in numerous formats such as HTML, PDF, EPUB3, or DocBook. This is due to the presence of an AsciiDoc processor which can parse and understand an AsciiDoc source document, the parsed document is then converted into any desired format.

One key advantage of AsciiDoc is its ability to parse documents into various formats and this enables it to be integral in static site generators, IDEs, CI/CD systems and other software. It is also quite easy to get started with as it only requires a text editor to read or write.

Test your knowledge:

QUESTION 1:

Which of the following statements about AsciiDoc is NOT true?

QUESTION 2:

Which of the following is not a format that AsciiDoc can produce document output in?

 

Exercise

Complete the following exercise before proceeding to the next module.

  • Briefly explain the relationship between ASCII characters and AsciiDoc markup language.

  • In your answer, explain how ASCII characters can be used in expressing the full content of an AsciiDoc document.

  • Make sure your responses are clear, well-structured, and that they demonstrate your understanding of the subject.

Make a post and tag @TechnicalWriti6 on Twitter to the link to your document.