Documentation written primarily for your own use is challenging for multiple reasons. Because no one will ever see it, do you care about creating a consistent method for writing and editing? Yes. A simple formula to follow will help lower the friction to creating it in the first place.
After it’s written, this text is not carved in stone. Your documentation will need to change as your business evolves. When you make updates, it can be helpful to write yourself a quick reminder why a particular section changed. Today I’ll explore a simple way to format this nudge.
Do you really need a system? It is tempting to edit and move on. While for the most part, these changes don’t need extra information, sometimes a short note will help you remember why a change was made without causing extra clutter in the document.
The easiest way to do this is to take a cue from programming and write a quick comment.
Why? It’s a consistent way to format this brief annotation so that you know it’s separate from the main content and your eyes and brain can skip it. It doesn’t need fancy formatting, such as a footnote or track-changes turned on.
As I want to keep these internal reminders concise, I like to use the single line comment format of a double slash, //.
What do I include? A quick note about what changed and the date. For the following example, please note that the date isn’t when I made the change, but in this case reflects when the postal rate went into effect:
Marking simple changes, example
Shipping rates, Priority Mail, Flat Rate:
- envelope $7.75
- small box $8.30
- medium box $15.05
- large box $21.10
// shipping rates increased effective 2020-01-26
If my comment is lengthier, I allow it to continue over multiple lines, I don’t bother with a proper programming block comment.
Why do I use this method? As it relies on text to mark the edit not formatting, it is more likely to outlive changes to my editing application. It’s not something I generally write so I can search for the character string and easily add or remove as needed.
The key is consistency.
