Create your first Documentation in AsciiDoc
Learn how to create technical documents in AsciiDoc. Plan, write and share your first project based on a real example.
Table of Contents
Technical editors live at the interface of innovation and comprehensibility. Their passion is to open up the complex worlds of new products and groundbreaking technologies to readers. Every day is a new learning journey that not only expands their knowledge, but also their ability to communicate that knowledge in a clear and accessible way.
Today we want to give you a new tool to help you create documentation effectively. To do this, we will work together to create the user manual for a fictitious electric car. Our aim is to provide you with a comprehensive guide that will lead you through the entire workflow - from initial planning to final publication.
This guide explains the processes behind technical documents. You can find out how to implement the individual commands in our manual. We have always linked it for you at the relevant points.
To create this documentation, we use adoc Studio, an advanced writing environment designed specifically for technical documentation. adoc Studio is based on AsciiDoc, a lightweight markup language known for its flexibility and simplicity. Even if you decide to work with another AsciiDoc-compatible tool, the principles and techniques shared in this blog will be universally applicable. AsciiDoc - unlike other markup languages - is on the road to standardization. This ensures compatibility if you import .adoc files from one editor to another.
Now let's dive into the project together.
Back to the Overview
Project Planning and Preparation
When writing technical documents, it is important to present concepts in a precise and simple way. To do this efficiently, you need to know your readers. Therefore, always consider who your target audience is. What do the readers already know about the product? Which technical terms need to be explained before they are used?
Who are your readers?
Your first step is to carefully research your target group. You don't always have to reinvent the wheel. In many cases, you already have a clear idea or even contact with your readers. This of course saves time and money. If this is not the case, you can get to know your readers better through your own Internet research or at events such as trade fairs. User interviews will give you an overview of their understanding and level of knowledge. But how many people should you interview? A rule of thumb is to keep asking questions until the answers are repeated. After 3-5 interviews, however, you should have gained an initial, rough overview.
The role of technical experts
Do you now know the level of knowledge of your readers? Then now is the time for you to become an expert on your topic yourself. To do this, we interview subject matter experts. SMEs (Subject Matter Experts) are a central point of contact for editors. They ensure accuracy and give your texts credibility. Coupled with their own research, subject matter experts give you the knowledge you need to explain concepts in a detailed but understandable way for your readers.
For our example, a whole range of experts can be relevant: Automotive engineers, vehicle electronics software engineers, energy and charging technology experts and more.
Interest in e-mobility has grown steadily over the years. To cover the entire range of users, we interview different groups of users: drivers who have already owned an electric car and those who have never driven an electric car.
Plan & Structure your AsciiDoc documentation
Have you done your homework? Then let's get into our writing environment and give our project an outline. We create a collective document and dedicate a separate chapter to each point in the outline. Our research so far has led us to the following structure for the operating instructions:
An outline is balanced if the number of sections and subsections in each chapter does not vary too much. It does not make much sense if a chapter contains only one subsection or section.
Before we start writing, one additional tip. Use the document header, i.e. all the lines that you enter above the title, to customize the content and design of your document. For example, write :toc: in the document header. You now have a dynamic table of contents which - at present - comprises the first outline level. Adjustments to the number of levels and the positioning of the table of contents are also possible.
But now we've done enough planning. Let's start writing.
Back to the Overview
Writing in AsciiDoc
Over the years, AsciiDoc has proven to be the markup language of choice for technical documents. The big advantage: the source code always remains easy to read. This means that getting started is comparatively easy. At the same time, AsciiDoc has a wide range of functions, allowing complex projects to be implemented with ease.
AsciiDoc separates design from content. This allows you to concentrate exclusively on writing. You can change the document layout at any time without having to adapt the text. We will come to this later.
As in any markup language, you can also format individual words in bold, italics or other ways. Below is a list of the most important markups in AsciiDoc:
Lists
A basic principle of technical documentation is to explain concepts clearly and simply. Continuous text is not always the best way to do this. For our example project, we use lists to:
Enumerations without order (e.g. to list all navigation functions) as an unordered list
Create step-by-step explanations with ordered (or numbered) lists
Provide care instructions for the seats as a checklist
Embed visualizations
The saying may sound more like a cliché nowadays, but there is truth in it: "A picture is worth a thousand words". images, tables and more help to illustrate complex issues. They give your readers orientation and help them to understand instructions.
A tip for inserting tables even faster: Use Apple Text Replacement in the system settings. This allows you to replace one text with another. Personally, I just write table() to create a table with a title, 3 columns and 2 rows. Here is the table if you want to copy me.
|===
| Title 1 | Title 2 | Title 3
| Column 1 | Column 2 | Column 3
| Column 1 | Column 2 | Column 3
|===
Blocks in AsciiDoc
AsciiDoc also offers blocks to separate information from the text flow. Admonitions are one of the most important block elements. They allow you to give tips, warnings, notes and more. For example, you can use TIP: to give your users a tip on battery-saving charging.
Other elements such as quotes, footnotes, user interfaces (e.g. to visualize keyboard shortcuts) are also quickly integrated. Always remember to focus on credibility and comprehensibility in your texts.
Digital navigation
Another basic principle of technical documentation is the intuitive operation of texts. Manuals have long since ceased to exist only in paper format. This means you can now structure texts much more intelligently.
Cross-references
We use cross-references within our manual to link individual chapters with each other. Do you have terms in your documents that require explanation? Then link it to the definition in the glossary at every point. This way, the term only needs to be explained once.
A tip to avoid errors caused by changing titles: Place an anchor ID before headings. This has the great advantage that the heading is not set as the reference and therefore changes to the title do not affect the reference.
Hyperlinks
We place hyperlinks on the Internet to refer to external sources. Our tip for recurring links: Define the URL as an attribute in the document header to repeat it at any time without having to enter the entire URL. Another advantage: If the path changes, you only have to change it in one place.
Intelligent documents
Probably the biggest advantage of AsciiDoc is the creation of intelligent documents. With the help of attributes and conditions, you can create a master document that adapts to the requirements of your readers like a set of building blocks.
Attributes
You will quickly learn to appreciate the value of attributes in AsciiDoc. These little helpers allow you to keep information consistent throughout the document without sacrificing flexibility.
It is very likely, for example, that you will mention the name of the electric car, various safety instructions or URLs to your company website several times. If changes need to be made to the text, you don't have to adapt each passage individually. Instead, define an attribute at the beginning of the document and insert it wherever you need it.
Conditions
Not all content is relevant for all readers. Our e-car is available in different model types and the equipment can also be configured. So if drivers have configured leather seats instead of fabric seats for their car, the manual must adapt to the configuration.
This leads us to the conditions in AsciiDoc. Conditions can be used to show or hide texts. To do this, we define an attribute and insert it into an ifdef condition. Now this text is only displayed if the "leather-seat" attribute has been activated.
Excursus: Design
As already mentioned, design and content are independent of each other in AsciiDoc. Now that we have created the content of the first draft of the user manual, we can think about the design. This is where the approaches differ. AsciiDoc must be output natively via scripts and converters. A style sheet can then be stored in this process. However, this style must be defined individually for each output and in different languages beforehand.
We take the simple route and use adoc Studio's supplied product styles. Here we have a selection of templates available that apply to every output format. This means that we use the same style file for both HTML and PDF. One click on the style and our entire project is redesigned. This is already a good start, but we want to adapt the style to our client's corporate identity. To do this, we duplicate a style that we like and edit the file. Using simple CSS skills, we create an individual style for our project and save it for future jobs. Adjustments to the font, document colors and more are child's play.
Back to the Overview
Editing and collaboration
Have you finished writing the manual? Then you deserve a breather. Give your document to someone you trust and ask for feedback. Have your text checked for content and language. Are the concepts explained clearly? Can the instructions be understood and implemented by users? It makes sense to involve your technical experts in the proofreading process. They can point out errors in the content.
So that you don't have to sit next to your proofreaders all the time, AsciiDoc has a comment function. Comments are written directly in the source text. As in programming languages, lines are not output if they are "commented out" with //. By the way: The similarities to programming languages have led to AsciiDoc texts being written and managed according to the "Docs as Code" philosophy. Read more about this in this blog post.
One document, many outputs
Our "master document" has now been created and corrected. Now we can output our manual individually, depending on the configuration. The key lies in multi-target publishing (or single-source publishing). The concept is simple: you have a single source document and create all outputs from it, which can differ in format (HTML, PDF, ePub, ...) or content (e.g. the configuration of the car). As we have already defined the attributes in the text, we only need to activate all the attributes that are relevant for the user in the output.
In adoc Studio, the output can be created entirely via the app. In traditional workflows, you often have to run complex scripts in the terminal to generate different output formats. However, this "terminal terror" is now a thing of the past. You define the output as a product and select the format, style and attributes.
Congratulations! You have now created your first documentation in AsciiDoc. But the journey does not end here. Continuous improvement of your documentation based on feedback is an essential part of the process. We encourage you to revise and optimize documents regularly.
Remember, practice makes perfect, so don't hesitate to put your newly acquired skills into practice. If you are looking for a writing environment for this, we invite you to try adoc Studio.
