Decisions in a short doc
An insight into the number of decisions a tech writer makes, even in a short document.
A few weeks ago, I completed a quick assessment exercise for a potential new client (I got the job - yay!) It struck me as I was working through it and annotating it just how many decisions we make, every time we produce a document.
The exercise was to write a sample of release notes for an imaginary product. You can view the Google doc here.
In less than two pages, I made eight decisions about style and content that I felt I needed to explain. In other words, eight points where I had to make choices with no absolute, obvious standard.
There are two key takeaways from this:
- The importance of style and tone guides
- Tech writing is a craft
Style and tone guides
A style guide, either for the whole company, or at least for the documentation team, allows you to standardise your preferences regarding each decision point. This ensures consistency, which is beneficial to users. For example, if you are consistent in always using bold to refer to UI elements, your readers can use this to scan through your docs quickly. They'll get used to the convention, reducing friction when consuming the docs.
In the long run a style guide also saves time for the writers. Once people are familiar with the it, they're able to implement its guidance, without hesitating over every decision point.
Tech writing is a craft
Your response may be "well, duh". However, this point is sometimes lost. Unlike coding, where you need to learn a specialist skill, or design, where there's a clear creative element and some people may "have an eye" for it, tech writing can appear less skilled. Almost everyone can write. With the growing popularity of docs like code, documentation tooling has become more accessible to developers.
This isn't intended as a defensive post, or an attempt to boost my market value (though to any potential employers: my market value is massive!) It's a reminder to myself, and a reassurance to new tech writers: learning to write technical documentation well takes time and effort. Don't be hard on yourself for your early attempts, and don't undervalue the skill you're mastering.