Comment by NortySpock

I would suggest you avoid thinking in too general of terms like this. There are dozens of kinds of docs. It's better to think about the document's specific purpose, audience, what you need to convey, what the audience wants to know, and how they want to absorb it. Then write, then read it as that intended audience, see if that person can make sense of it, and if it provides enough information. If you can't put yourself in their shoes, have the audience proofread it.

Two important lessons I learned:

1. Formatting and direct communication is very useful. It can make the difference between someone stopping and noticing critical information, or skipping it because they're lazy readers.

2. You probably don't know the correct way to convey information, and the audience probably doesn't know how to tell you how to convey it either. You need to listen for when the docs fail: when somebody says they read the docs but still don't know something or don't do something right. That means your doc has a "bug" in how it gets through to the reader. Experiment, change things around, add/remove information, etc until the bug is gone.

Agree with the sibling comment, but a starting point is also just to write docs for your future self, which is usually going to be type 3 or 4. Most of us who have been programming for a few years have had the experience of being mystified by something we ourselves wrote in the past, so it eventually becomes fairly straightforward to predict what kinds of things future-me will need a hand in piecing back together.

And it turns out those kinds of docs are pretty useful to my colleagues in piecing it together also.

In contrast to the current sibling replies, I think this is a very fitting categorization of documentation. Off the top of my head, I can think of several examples where one type of documentation is excellent but others are very lacking, for example:

* Rust Library Documentation: Most libraries have complete and up-to-date reference documentation, but are lacking even basic introductions (tutorials/guides) on how to use the library. This is totally just my personal experience so maybe I've been looking at the wrong crates, but with most of the crates I spend several minutes looking trough all the modules in order to find that all the juicy functions are hidden in the Connection struct, or something similar.

* Linux Kernel Documentation: The Linux kernel has excellent in-depth explanations on several high-level concepts, but on the other hand a little more systematic reference documentation on the supporting library code would help a lot.

* While I can't think of a good example right now, a lot of projects have a few basic getting-started tutorials but don't explain advanced concepts or high-level design at all, leaving you to wade through the sources yourself in order to understand how to actually use them.