[jumpman500]

The code, tests and data is the documentation. If the code is clear the documentation should be short description of features and purpose. Explaining how to setup a development environment is nice for onboarding.

Everything else is noise and leads to worse understanding. You have a duty to document but you also have a duty not to document irrelevant details or workarounds that aren’t real solutions. Bad documentation is a waste of your time and others.

[bad_username]

Documentation to code is what a database index is to database data. You can do full table scans but indices speeds up things by orders of magnitude. Similarly you can piece a big project picture together by reading all the code, but it will never be as fast as reading a good architectural overview or a description of concepts.

But, as a corollary, do not document what can be inferred quickly by looking at the code. I think that doc generators from code doctrings are not very useful.

[maxvt]

I would not suggest people to follow this in 2024 if they are building any system of non-trivial scope and expect it to be adopted by others who are not required to adopt it.

Back in 2017, I compared "code as documentation" to being dropped into on the street of an unfamiliar city, while a good documentation can serve as a map of the city. [1]

Nearly all recent successful efforts for large new systems understand the value of both high-level overviews and detailed examples / onboarding materials to make adoption easier. When solutions to a certain problem are abundant, people do not need to settle for options that do not have great supporting documentation of the four primary kinds. [2]

[1] https://speakerdeck.com/maxvt/i-got-a-lot-of-problems-with-i...

[2] https://documentation.divio.com/

[andrewjf]

Completely agreed. Most documentation, for this reason, is basically useless because it's just wrong enough to be completely misleading and outdated virtually immediately. It takes a massive amount of investment into documenting internal stuff, just don't do it. Write clearer code, use commit messages as to the 'why'