Post History

Source: https://writers.stackexchange.com/a/35019
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

Source: https://writers.stackexchange.com/a/35019
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

The goal of a technical documentation is to tell the reader what they need to know to continue working. They are not interested in reading a nice play on words or particularly interesting ways to phrase something. They are looking for a text that's easy to parse so that they can find what they are searching as fast as possible.

With a novel or something similar you are looking to entertain yourself. When reading you just want to _read_, you want to get absorbed in the world that someone else is describing there.

With a technical documentation you are looking to find some information that helps you to continue your work. Maybe you don't know which steps to follow to restart a service. In that case you don't want to read something about the ideas that went into the design of the UI or the processes that led to the decision to put _Button A_ to where it is - you want to read the steps to restart your service. And you want them _now_. Because you need them _now_. Every minute that you spend reading something creative is a minute of work time lost and potentially a minute of downtime.

The guidelines are there to ensure that even critical problems will be solved as fast as possible. Your specific problem may not be _that_ critical, but some problems _are_ that critical, which leads to such guidelines.

The next thing to keep in mind is that you should try to write in a way that is easily understood by everyone who is familiar with the context. If there is a certain style to technical documentation in your company then you want to adhere to that style so that everyone who knows something about technical documentation in your company can parse your document as quickly as possible.

That means that you will often have to introduce a way to phrase certain things that may feel a bit unnatural or clunky from a _creative_ perspective. But by having these standard phrases it's easier for others to decide whether that paragraph is important to read.

People who read technical documentation rarely have time. And they never have _enough_ time.

That's why it's important to write without any _creative_ sections, even if the deadline is approaching. Because if you fail to fix these things that are not-really-problems-just-differences-in-style then you can be sure that someone will trip when trying to find something important in one of your documents at one point. And every minute _may_ count in such a case.

Original score: 7