All the general rules of technical documentation apply, but there are some extra quirks inside the tech industry.
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.