This is an old revision of the document!

I strongly appreciate excellent technical documentation. You can have a great piece of software but if it's difficult to understand how to use it, users will fail to appreciate it.

Because I appreciate good documentation for tools I use I do my best to write useful documentation. In addition to the obvious benefit, which is that good documentation saves everyone time, I find there are several additional benefits specific to the act of writing documentation:

• Writing about a subject cements, organizes and structures knowledge in my mind
• The process frequently reveals areas that I lack knowledge in or don't fully understand
• Collating and structuring information often reveals performance or security issues that I hadn't seen before
• It improves my general writing skills, vocabulary and cognitive processes

A common pitfall I see is that people who write documentation turn very hostile towards users who ask questions covered by the documentation. I used to be this person. User asked a question? Oh HELL yeah, now I get to berate them for not reading the FUCKING MANUAL!

This is stupid. Most users are asking questions for one of these reasons:

• They didn't know where the documentation was or that it even existed
• They could not find the information they needed in the documentation
• The documentation was not clear

If you work or play in technology at all, you have likely been in each of these scenarios. Put yourself in the user's shoes. In nearly every case a user asking a question is not an annoyance, it's an opportunity to do two things:

1. Improve the documentation
   1. If the user couldn't find the docs, how we make it more discoverable?
   2. If the information already exists but they couldn't find it - how can we make it easier to find? Should we structure the docs differently?
   3. If the reader couldn't understand the information, this is a perfect opportunity to identify a deficiency in clarity. How can we explain it more clearly? Odds are other readers are having issues too.
2. Improve the user
   1. If we contribute a documentation fix in response to a user concern, it demonstrates to the user that the docs are actively maintained. This makes them more likely to use them.
   2. For users who do not believe in writing docs for their own things, it demonstrates by example why the docs are useful

Now, yes, there are the users who show up, ask questions, are referred to the documentation and become combative, refuse to read it, are insulting, etc. Documentation helps us in dealing with these users as well. If the information is well documented, you don't have to interact with them at all! Just refer them to the documentation and move on. You get to completely avoid interacting with toxic people.