Software projects need to have good documentation. This makes the software more approachable and impacts its users and contributors. More importantly, it increases the software’s signal-to-noise ratio, allowing developers to better understand if the software meets their needs. This is not revolutionary: high-level software developed today (i.e., using the C programming language or above) presumably uses third-party code, open-source or not. Writing software documentation, however, is challenging and thoughtful work. This is the reason why technology companies hire technical writers and developer advocates: they know good documentation is critical for their product.
Markup languages,
such as Markdown and AsciiDoc,
have become essential in developing software documentation.
Their similarity to programming,
with toolchains and a lightweight syntax,
aligns with the developer mindset more so than traditional word processors.
Documents written in them have a low barrier to read
(e.g., you need only a text viewer installed, like more)
and easy to read diffs,
making their history easy to track using a version control system.
Like software source code, markup languages allow authors to write the same content a thousand different ways. With this type of flexibility and creativity in the documentation process, it helps to employ techniques to make writing documentation as enjoyable as writing code and to make the documentation source files as aesthetically pleasing, consistent, and efficient as well-styled source code. This post shares four such techniques that have improved my writing experience.
[Read More]