How to Build a Professional Technical Writing Environment (Using Free Tools)

Learn Docs-as-Code basics, get started with DITA, and generate your first XML-based manual

Microsoft Word. We all know it, we all use it, we all either hate or love it.

While it has its purposes, writing professional technical documentation is not one of them.

• It is too slow and unstable to create large documents.

• It is too liberal with formatting, which is paramount for professional user documentation.

• It isn’t easily integrated into existing code generation pipelines - an advanced topic.

Today, you will learn how to set up a professional documentation environment.

In this tutorial, you will:

• Learn the principle of Docs-as-Code and its benefits.

• Learn the concept behind XML-based documentation with DITA.

• Install your own professional DITA-based authoring tool.

• Generate your first(?) single-source, XML-based user manual.

What is Docs-as-Code?

In software development, fast delivery is key.

Some years ago, developers produced code for an extended time, say, one year. At the end, all of it was tested and, eventually, released. As you may tell, this was a very inflexible process.

Then, agile came along and replaced this so-called waterfall model with new principles. CI/CD was born - continuous integration and continuous deployment.

What this means is that the main code base is always kept in a releasable state. This is done with continuous testing.

Docs-as-Code supports this model by maintaining documentation in the same way as regular code:

• Same or similar editing tools

• Same version control management (often, Git)

• Same build pipeline (the tools that compile and release the code or documentation)

Most of the time, Docs-as-Code is used as a synonym for simple markup languages like AsciiDoc or Markdown. But it is not limited to those.

Instead, it comes down to how you manage the source files of your documentation. XML-based environments can be considered Docs-as-Code, as long as they use similar tools to those for regular code.

The opposite would be to rely on out-of-the-box tools like Content Component Management Systems (CCMS). Examples of such tools are Madcap Flare, SCHEMA ST4, or Cosima.

Such tools are powerful and allow for advanced variant and translation management, just to name two features. Yet, they are quite heavyweight and expensive.

That’s why many companies, especially smaller ones, have to settle for cheap or free open-source software.

Guess what?

Docs-as-Code is perfect for this!

To DITA Or Not To DITA…

Docs-as-Code is typically associated with lightweight markup languages, such as Markdown or AsciiDoc. Their syntax is very simple and easy to learn.

While these languages are gaining traction fast and have their advantages, XML-based standards like DITA still have their benefits.

DITA provides semantic formatting compared to the generic formats in Markdown or AsciiDoc. Consistency is crucial in technical documentation.

Generic formats, such as bold or italic, rely on authors to manually apply consistent formatting. That’s an error-prone process.

With DITA’s semantic markup, such as <guilabel>, you name text elements as what they are instead of how you want to format them. This contributes significantly to consistency within and across documents.

The reason I chose DITA for this tutorial is not just for its consistency. It is mainly for educational purposes.

The vast majority of professional technical writing teams still use XML-based authoring environments. My goal is to equip you with the knowledge you need to establish yourself as a technical writer.

That’s why you should learn an XML-based language, which DITA is. If your future employer happens to use AsciiDoc or Markdown, you will be able to transition quickly. The learning curve is much quicker than with DITA.

If your employer uses another XML standard, you can easily transfer your DITA knowledge. The tags might be different, but the principle is identical.

Learn DITA and you’ll be prepared to face virtually any authoring language out there.

The best part about DITA: The DITA Open Toolkit is open-source software that is freely available. It contains all the tools you need to generate DITA-based documentation in various formats, like PDF or HTML5.

You can download it now and use it immediately. Using it is a bit trickier, as it is a command-line tool. I will show you how to use it later.

Generating a PDF document with DITA Open Toolkit from the command line.

Setting Up An Authoring Tool

The only limitation of the DITA Open Toolkit is that it doesn’t include an XML editor.

Oxygen XML Author or XMetaL Author are powerful tools that aid you in creating DITA documentation. They make sure you structure the document according to DITA’s rules and even provide generation scripts.

You don’t even need to install DITA Open Toolkit separately, as these tools come with their scripts to generate the documentation.

The downside? They are expensive.

That’s why we will stick to free tools, which leaves us with these:

• Notepad++ (or any other text editor)
  Great tool, but it doesn’t fully support XML validation and catalog resolution, which is essential to work with DITA effectively.
  You can still use it to edit DITA content, but you must be familiar with the required XML structure. Not for beginners.

• VS Code with Extensions

  With the two free extensions XML (by Josh Johnson) and XML (by Red Hat), you get useful XML features, like autosuggesting allowed XML tags based on context or content validation.
  The problem is that catalog files are not fully supported. I will spare you the technical details. Let me put it this way: I spent several days trying to get it to work. I have not found a single promising configuration.

• XMLMind XML Editor
  This XML editor is free for non-profit organisations or private individuals. This makes it our ideal tool to learn DITA.
  It is not as powerful as XMetaL or Oxygen, but it gets the job done. In my tutorial, I will show you how to use it.

---

We have all the basics. The only thing left to do is to actually do it.

For my paid subscribers, I have prepared a screen recording to guide you through all the steps to:

1. Install DITA Open Toolkit.

2. Generate your first DITA document using the Windows command line.

3. Install and configure XML Mind XML Editor.