Post History

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

Most of the time, the answer to this is structuring of the writing. I work in Software development, and you are right that a lot of technical documentation is appallingly overdone.

The straightforward answer is to take stuff that is written more than once, and write it once in a definitions or explanations section. It is rather like refactoring code - take the verbosity out and put it centrally, so that you can see the flow of the code, and only refer to the details at the points you need to.

Ideally, someone who knows the system fairly well, should be able to look at a short page of technical instructions to find out how to do something they have not done before. At the same time, a new user should be able to achieve the same thing, but probably looking up a lot more of the details (What is a Doodlesquat? Where is the Diddle control? How do you Activate The Centuran Protocol?)

Writing good and clear technical documentation is a really difficult thing to do, as demonstrated by the general quality around.

Original score: 8