[ricardo_ramirez]

This is personal, but I taught myself how to code, before the internet, and with barely any books. One thing that made, for example, the PHP documentation a lot easier to read vs. Perl was: examples

On an API level, don't just explain what things do, but how to use it, what is the intention behind a particular call or method, and how it integrates with other pieces of the environment. If there are best practices, this is the place to call them out. And it does not need to be a tutorial, but if the class calls for a "usage sample", that is perfect for the documentation.

Pick on these: 1) What decisions did you take for the implementation? 2) What tradeovers are made (this is written like this because ...) 3) How is it supposed to be used 4) What is the common pattern for accessing the resource (instantiate it, factory, singleton, dependency injection?) 5) How does it relate with the rest of the codebase?

Now, this is PHP, but on other languages... 6) Is it Thread-Safe? 7) How cheap is it to instantiate a new object of that type?

[Fizzadar]

This, self-taught as well starting with PHP and their docs (with examples and user-added examples) are the best I've seen.

I've also noticed a lot more packages (npm mostly) with synopsis sections which essentially forms a 'full example', I find these immensely helpful.

[progx]

Yes php-documentation is really beginner friendly because of the small examples and the comments.

One of the best documentations ive seen in the last time was from phalconPHP http://docs.phalconphp.com/en/latest/index.html

Well written and many comprehensible examples within in the doc.

I think, that writing a good documentaton is harder than programming.

[superice]

These are some very good points! I already try to explain in my documentation why I wrote the code like I did, but I guess I'm afraid I'll bore the reader to death with it. Describing common patterns, or good practices is also something I try to do regularly.

The relation to the rest of the codebase is something I don't really get: do you mean I should explain why this piece of code is consistent with other code? Or the documented code interacts with other pieces of code?

[natdempk]

I would imagine the relation to the rest of the codebase is how/why it interacts with the rest of the code. This is often valuable to know as its rare you are using just a single piece of a codebase in isolation, and relations among pieces are very helpful for developing intuition about them and the codebase as a whole.

[bencollier49]

You taught yourself PHP before the internet?

[raamdev]

It wasn't stated which language was learned before the Internet, only that (s)he learned how to code before the Internet.