Technical Writing

As a group of senior developers, focusing on cross-platform, mobile, web and desktop development … and who wrote all of the docs for the applications that we created … we were born to be docs-as-code technical writers.

We know how to work with your developers to produce the best documentation for your needs. This does not mean creating a massive, never-read pile of docs; but what your users need, to understand your system instead.

We write FAQs, White Papers, System Docs, API Docs, Brochures, Social Media Updates, WIKIs, Product Reviews and Articles for your site. We also can provide UI copy for your applications.
We would love to help … please give us a try.

Docs-as-Code vs DITA/XML
June 2024

There are currently two main approaches to technical documentation. Docs-as-Code (hereafter "DAC") and DITA/XML (hereafter "DITA"). Well, OK. There really are three current approaches … with the third being "no documentation". We do not generally advise using the third approach.

Both the DAC and DITA methods result in nice-looking system documentation; but how they get there is very different.

DITA

DITA (Darwin Information Typing Architecture) uses specialized, and costly^‡, tools to create docs. Even worse, DITA requires specialized knowledge to use these tools. It sort of forces needing a new class of employee — a Writer with specific knowledge of these tools. DITA Writers may come in different flavors. They can be more development-oriented; or more oriented towards graphic design. The latter may or may not be the best to translate developer SME notes into usable documentation.

DITA tools generally store their information into a Content Management System (CMS) that must be separately maintained; and also understood by anyone (like Managers, or Marketing staff) who wish to pull content from the CMS.

One of the strengths of DITA tools is potentially also a major weakness. With DITA, chunks of text are formatted and stored in a CMS. These same chunks can be easily retrieved, so that they can be reused. And reuse them, people will do. And do. And do.

Other writers pull these blocks of pre-done text from the CMS to use in their own articles — and this is considered to be a good thing; as it saves writing time and ensures that the "message" remains completely consistent across time (and across writers).

So, the same blocks of words pop-up in many different articles; and the resulting effect is that of a foreign copy-producing sweatshop (or, AI-driven content) … that is cobbled-together and/or plagiarized.

On the Other Hand…

Docs-as-Code

The second major approach to technical documentation uses the tools already familiar to the developers themselves. Documentation is not kept in an unique CMS that requires specialized skills to use; but rather right on the same platform that the code itself is kept. For example, many open-source projects keep their code in a git repository (like Github, Gitlab or Gogs … a git repository that you can host yourself).

git is the actual tool used to move the files into/out of the repository. git is widely used and is open source software.

If your organization does not use git, DAC documentors would use whatever the developers do use. That way any developer, as well as any other documentor, would be able to help a new hire to come up to speed quickly.

This allows each organization to adapt the documentation process, or even to alter the actual documentation tools themselves -- IF they desire to do so. You can't do this with DITA tools. In fact, when using DITA tools you should plan on adapting their way of doing things, rather than keeping your own.

Often, docs-as-coders use a regular, spell-checking text editor to create the documentation. Just as often, a simple markup toolset, called Markdown is used to do things like adding styling (bolding, italicizing, creating headings of various sizes, and even things like tables) in the text.

Markdown is similar to HTML tagging, but with much simpler syntax.

For example:
To create this line:
This is the way to use Markdown correctly to show this code: SELECT * FROM users; on lavojo.

Would be this, using Markdown:
This *is* the **way** to use Markdown ***correctly*** to show this code: `SELECT * FROM users;` on [Lavojo](https://www.lavojo.org).

And something like this, using HTML:
This is the way to use Markdown correctly to show this code: SELECT * FROM users; on <a href="https://www.lavojo.org">lavojo</a>.

Even if you used the HTML <code> tag, it would still require separate styling to show the code in color; as the Markdown readers provide by default.

The entire La Vojo blog, is done with Markdown and a text editor. For more about Markdown, see the Markdown Cheat Sheet.

In Summary

It feels a bit as though DITA tools were created to fill a need that is not there. While it is true that such tools can be pushed into large organizations via lobbying, "etc"; and will certainly enjoy the support of those DITA writers already in place; they may not be necessary. At least for technical writing, Docs-as-Code tools are more closely matched to source of the content (Developers); are much more flexible; and are most certainly far, far less expensive.

   ^‡ DITA Tool Costs, June 2024
Madcap Flare: $195 to $311(USD), per user, per month! More for enterprise CMS.
Oxygen: $568-$1300, per year.
RoboHelp: $39 per month for single user. You get to call them for enterprise pricing.

There are free versions of DITA tools, but they never show up in any of the job requests that we have seen.

Again -- the biggest cost of DITA is that you'll need specialized staff to use them.
Now.
And into the future.
     Docs-as-Code Costs, June 2024
Markdown:  $0
Git: $0