Technical Documentation: Why Write Stuff Down?

Technical documentation can be extremely difficult from how advanced it is, but it’s absolutely crucial.

Whenever the design of the interface/hardware doesn’t communicate the concept explicitly (which is extremely common), the user needs the software engineer to communicate exactly what the user can do and precisely how to do it.

For this reason, technical people need to understand how to write well or get assistance from others who are skilled at it.

The absence of good technical writing sabotages the entire community around the software:

  • Other technical people who have to work on the project will spend countless hours of rework just to figure out what the original creator did.
  • Non-technical people in positions of leadership and decision-making will have trouble knowing exactly what to do in many situations, which means they won’t be as willing to support advantageous decisions for that project, such as extra funding.
  • Non-technical people outside of the project won’t be as quick to adopt the software, especially when it’s open-source.

Git Commits

To keep track of what you change, it’s critical to maintain good notes, especially when things break. Thankfully, Git has the feature built-in with mandatory notes for “commits”.

There are a few important ways to write good Git commits:

  • Explain what you changed, why you changed it, and what it affects. Assume the reader has no clue what you’re addressing.
  • Capitalize the first word and don’t end with punctuation, though Conventional Commits are all lowercase.
  • Use a direct, to-the-point tone of writing (avoid kinda, I think, maybe, et al.).
  • Specify what commit type you’re making:
    • feat – new feature comes with the changes
    • fix – fixed a bug
    • chore – changes that aren’t fixes/features that don’t modify src or test files
    • refactor – redesigned code
    • docs – updates to documentation such as README
    • style – changes that don’t affect the code’s meaning, such as whitespace or missing semicolons
    • test – adds new/more tests
    • perf – performance improvements
    • ci – “continuous integration”: merging multiple developers’ work
    • build – affects “build system” or external “dependencies”
    • revert – restores a previous commit, often because something broke
  • The first line is 50 characters max, and the body is 72 characters max.

Changelogs

When software gets updated, people need to understand what happened and why. While it’s tempting to dump system logs into it (such as a git log), the purpose of a “changelog” or “release notes” is to allow a technical person to understand what changed without having to observe the source code directly.

There are several things to always do in a changelog:

  • Specify any changes that significantly change. Keep track of them in a streaming format (usually with the latest version change at the top, and adding new versions above it). Avoid informing much about minor changes that don’t affect the user.
  • Keep the information simple for the users. They never need to know exactly what lines of code changed, but they do need to know how it changes the way they interact with the software.
  • To avoid confusion on dates, use the date convention of YYYY-MM-DD, which goes from largest to smallest order.
  • As of 2022, there is no reliable universal standard for changelogs.
  • If a version was “yanked”, it’s still important to indicate the changes if the version was publicly released, often by putting [YANKED] after the version number.
  • It’s perfectly fine to rewrite changelogs. Just make sure that it’s clarifying or adding information, such as unspecified releases, and make sure to not devote too much time to it when you should be doing something more productive.

Data Visualizations

The domain of visualizing data is a geekier implementation of standard graphics development, but its most valuable use is in depicting technical concepts. For that reason, it does broadly classify as “technical documentation”.

The simplest form of data visualization is via markdown text. It allows for rich text formatting in plaintext documents. However, it never allows for much latitude in visual diagrams.

For many visualizations, Unified Modeling Language (UML) allows for quick text-based sketches of diagrams.

Many technical software honor UML and markdown, which opens up many varieties of graphical possibilities for a pleasant user experience.

Also, ASCII is monospaced, so it can be used to make ASCII charts and diagrams, beyond simply ASCII art.

Further Reading