Homepage
Login
New Post
Profile
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.
(0)More posts by @Jamie945
Terms of Use Privacy policy Contact About Cancellation policy © selfpublishingguru.com2024 All Rights reserved.