====== documentation ======

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, at best users will fail to appreciate it and at worst huge amounts of time will be wasted and vast quantities of errors committed.

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:

  - Improve the documentation
    - If the user couldn't find the docs, how we make it more discoverable?
    - 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?
    - 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.
  - Improve the user
    - 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.
    - 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.

===== 'code is law' =====

You probably know, or you may yourself be, a person who takes an attitude along the lines of "docs suck, code is law. [[just]] read the code lol."

There's a lot of potential things that can be going on in this person to cause them to take this view:

  - They suck at writing and therefore don't want to do it. This is the case for many, many people. Writing good, clear documentation is not a natural skill for most. You need to develop it.
  - They have an ego and it makes them feel superior to imply that you lack skilz because you can't efficiently comprehend an entire software package in an hour or two by simply reading the code. This is very common in junior engineers and people who are good at computers but lack well rounded social skills.
  - They have been burned by out of date or poor documentation in the past and reacted to this by distilling the experience into the opinion "docs = bad"
  - They know that documentation takes a lot of time and value either the experience or the result (or both) of technical work more, and therefore need a reason to argue against producing documentation if questioned

I think all of these are bull.

  - If you suck at writing - this is an opportunity to get better
  - If you feel the need to flex on people - grow up
  - If you have been burned by documentation - who said you had to make bad docs? Be the change.
  - If you want to write code - I feel for you. Don't you want people to use that code?

The last point brings up an important point - if you have zero interest or responsibility for anyone else to use what you're writing, by all means, do not write docs if you don't want to. I am not saying that you need to document everything you make. But for things you intend other people to use, writing docs will make them love you. If you do it professionally, I will double down and claim that competency in technical writing is part of being a well rounded and competent engineer.

===== culture =====

In a professional context, company culture frequently does not incentivize documentation. Technical output is rewarded. Documentation output is not. This is extremely common, but it is bad for the organization as a whole. Suppose you commit an engineer to building out a complex system, but there are no cultural incentives for the engineer to write good documentation, so they don't. How many man hours are subsequently wasted by users who are forced to reverse engineer that system in order to use it? Probably a lot, right? Imagine if the engineer was rewarded for writing good documentation and did so. Yes, the engineer spent time writing documentation when they could have been doing technical work. But how many hours are now saved for other users?

Of course, some teams are explicitly aware of that tradeoff. Externalizing cost to other teams means your team can be more productive - at the cost of the org. Dsyfunctional workplaces incentivize this behavior.

In extreme cases, this can result in the entire product being rebuilt by a different person or team because no one can understand how to use the first product.

At work we have an internal service that has an HTTP API. Said API requires authentication. Yet, nobody has bothered to write down how you actually authenticate to this service. It's extremely simple, so simple you can explain it with just two lines of example shell code. But somehow nobody has taken the 2 minutes to locate an appropriate place to write that down, jot it down and provide a couple notes on it.

What are the consequences of this? Now every time someone wants to use that API:

  - The user must locate an appropriate channel (email, slack, etc) to ask their question
  - Ask their question and hope a knowledgeable person (KP) sees it
  - Said KP must now explain how to do it - probably not for the first time (!)

This entire transaction is repeated countless times. Consider the alternative:

  - User asks a question
  - KP sees the question and instinctively reaches for the docs to give the user
  - KP realizes there are no docs. KP spends 2 minutes creating a docs page, writes down the answer, gives it to the user.

Now the user has that docs page to share with anyone facing the same problem and KP can spend less time answering that question in the future. This saves everybody time and improves morale.

===== docs pitfalls =====

Hitting these issues are also reasons why people form the opinion that docs are bad.

==== the docs are too detailed ====

I have seen "docs" that go into excruciating detail. Sometimes, like in formal API specs in safety applications, this is necessary. But for many products it is not, and it will cause many problems:

   * The docs will go out of date very rapidly
   * Engineers will spend extreme amounts of time keeping docs up to date, impacting productivity and reducing morale (engineers enjoy building)
   * Users will frequently encounter incorrect documentation, lowering trust in docs overall, increasing support requests, impacting productivity