I write technical documentation, heuristic reviews and terrible puns.
How I maintain consistent documentation
Though clear, definitive documentation style guides and documentation library governance, organisations can achieve consistency, clarity, and professionalism across all their technical content.
I have created and maintained technical documentation style guides for multiple organisations, and acted as a contributor, maintainer and reviewer of documentation libraries.
Below, you will find some examples of my style guide work, and examples o tasks I have performed when maintaining a documentation library.
Technical documentation style guide excerpts
Excerpt 1: Capitalisation
In titles
Technical documents use sentence case, e.g. “How to open a stuck desk drawer”.
In dot points
Dot points generally form part of a sentence, so require punctuation and capitalization in the same manner as you would a sentence.
For example:
Wherever possible, feed your programmers with a variety of
-
baked goods,
-
caffeinated beverages, and
-
pub lunches.
In inventories
Use lower case for the first word of the items in your inventory, unless they are proper nouns (e.g. product names).
For example:
3x hamster wheels
1x MegaServer 22078
5x hamsters
Excerpt 2: Formatting numbers
Numbers are sometimes written out as words, and sometimes presented numerically. Below is a table outlining common number uses in our documentation.
Metric or imperial measurements?
As a global company, this is somewhat a case-by-case basis. However, there are some general rules:
Distance and temperature
In almost all cases where mentioning distances and temperatures, provide both metric and imperial measurements.
Common industry measurements
There are some measurements, particularly when it comes to hardware and hardware tools, where a single measurement is near-globally acknowledged and used.
For example:
-
a 3.5” floppy disk, or,
-
a 1.5mm ball screwdriver.
In these cases, you would not need to provide alternative measurements, as the measurement is commonly accepted and understood within the industry.
Excerpt 3: Describing product states, inputs and actions
The below guidelines outline ways to use consistent, clear language about interacting with our products.
Audible feedback
When describing sounds someone may hear while using our products:
-
When does the sound occur?
-
Is it a click? A beep? A klaxon? A series of notes increasing in pitch?
-
Is the duration significant? While a click implies a brief sound, a beep could be short or it could last for several seconds.
-
Is the sound high pitched or deep?
-
Should the user note where the sound is emanating from?
Tactile feedback
When describing tactile feedback someone may encounter while using our products:
-
Will they feel a click, even if there is not an audible click?
-
Will they feel a connector disengage or loosen?
-
Are there any textures that communicate valuable information? (Useful when a user may not always be able to see what they are reaching for).
LED light states
LED lights can communicate a variety of things through their illumination and activation patterns. Consider the following when describing an LED light’s state:
-
Is it blinking? A blink implies a light in a simple on/off state, with no variance in illumination.
-
Is it flashing? A flashing light implies one that is varying in luminosity (such as lights you may encounter on emergency vehicles/roadworks signs).
-
Does it illuminate once, twice, three times?
-
Does it blink or flash in a particular pattern?
-
Does it flicker? (Sometimes referred to as ‘warbling’)
Pressing a button
When a user needs to press a button, consider:
-
Is it a single, short press?
-
Do they need to hold down the button for a certain duration?
-
What feedback will they receive when the button is pressed?
Maintaining a consistent document library
I have extensive experience managing documentation in Git-based CI/CD environments, particularly GitLab. On past projects, I have collaborated with engineers to review and refine merge requests, ensuring adherence to our technical documentation standards.
The tasks I've performed to keep our documentation libraries consistent include:
-
Maintaining a clear information architecture - every piece of documentation should have a logical, consistent home. I ensure that a basic overview with a hierarchy of topics is made available to contributors via the repository's README file.
-
Establishing a consistent folder structure (e.g., guides/, references/, faq/).
-
Ensuring proper frontmatter metadata (if required by the static site generator).
-
Developing a technical documentation style guide. This includes formatting standards, tone, and terminology guidelines.
-
Defining standard Markdown syntax for headings, lists, links, images, and code snippets.
-
Tagging documentation versions to match software releases.
-
Creating a contribution guide that guides documentation contributors and reviewers through steps such as submitting merge requests, code review processes, and branch naming.
-
Creating templates for common documentation types (e.g., "How-To Guide," "API Reference").
-
Using comments and GitLab's suggested changes feature to provide feedback on contributor documentation.
-
Periodically reviewing documentation for outdated or incorrect information.
-
Defining criteria and a process for archiving or removing obsolete content.
-
Acting as a bridge between engineers and end-users to align documentation priorities with user needs.
“[Wendy's] ability to translate complex technical concepts into clear, concise, and accessible content for a variety of audiences has been a great asset to SoftIron.”
Kenneth Van Alstyne, Chief Technology Officer