Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

Post History

50%
+0 −0
Q&A Should creativity or eloquence in a technical document be removed during review?

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 p...

posted 6y ago by Secespitus‭  ·  last activity 4y ago by System‭

Answer
#4: Attribution notice removed by user avatar System‭ · 2019-12-12T23:01:22Z (over 4 years ago)
Source: https://writers.stackexchange.com/a/35019
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/
#3: Attribution notice added by user avatar System‭ · 2019-12-08T08:31:21Z (over 4 years ago)
Source: https://writers.stackexchange.com/a/35019
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/
#2: Initial revision by (deleted user) · 2019-12-08T08:31:21Z (over 4 years ago)
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.

#1: Imported from external source by user avatar System‭ · 2018-04-12T07:44:55Z (almost 6 years ago)
Original score: 7