> I have mixed feelings around documentation because I can often read the code faster than the docs, and docs are often incomplete, inaccurate, and out-of-date.

The problem I have everytime time I read or hear this statement, is that code is excellent in telling "what" happens, but often very opaque in "why" it's done like that. If the why isn't clear, code might be changed/refactored and stuff breaks, because the developer didn't understand the reasons behind the apparent code smell. It's comparable to Chesterton's Fence [1].

I much rather have some additional documentation than "self-documenting code" that does (apparently) weird things and tells me nothing about the reasons. Also outdated documentation can be helpful, when it's version controlled. That gives you context how the code evolved and if it doesn't state it directly at least pointers why the code is like it is now. That's also why I mostly prefer in code documentation to Confluence/wiki documentation, because the time/change relationship between code and wiki is much harder to comprehend.

[1] https://en.m.wikipedia.org/wiki/Wikipedia:Chesterton%27s_fen...

The problem with "Read the source, Luke" is that even if the code is well written (and that's a big if), reading the code only tells you _what_ it does, not why, not why it doesn't do it differently, nor what it may or may not do in the future. It's the difference between programming and software engineering.

While reading 'teh codez' can work for a (simple) app it will get you nowhere regarding the whole service architecture/infrastructure.

There can and will be several services/apps working together, external services required for some stuff, different set of configurations for different environments, CI/CD, software packaging, etc...

How we deal with it where I work - service developers/owners are responsible for providing docs for their services. Ops provide infra/CI/deployment/high level 'how all this works together' docs. Everything that can be code, should be code - with it's documentation. Of course there's issue tracker, wiki, commit messages all tied together using issue tracker IDs, etc.

And it still takes time for new people to get their heads around the 'how everything is working together'. Amount of docs we're writing is significant. Some of the docs is auto generated. Time for docs keeping is accounted for at estimating the time required for developing new features. Being a member of a remote team I can't imagine how we could be able to work otherwise.

The way I like to think about a well documented system is:

- unit tests show how well the developer understood the requirements at the time they wrote the code - git commit history shows who and when something changed (probably assuming history not rewritten :) ) - git history can be more informative, if and it is a big if, the developers write enough information and not just “changed code” type comments - in-line comments are for “why” - explaining things that look odd or go against standards or best practices, or “I’m doing this now like this, when x is available use that” - notes to help you and others - wiki is for higher level “why” to help people understand the code, where there is a lot of complexity I really like the idea of a “book of the xx” like the book of the runtime here: https://www.hanselman.com/blog/TheBookOfTheRuntimeTheInterna...

Your position is reasonable. The value of spending time on documentation in a vaguely specified and frantically written web app is not the same as, e.g. writing documentation for the frameworks that drive that same application.

Even with the most frantic half effort of a project, its helpful to give the context of why you are doing it, why you approached the project this way, and why you ended up not going with another approach. Maybe you did try what should have been the best approach at first, and it didn't work right, so you had to do something not as good but good enough. Then in the future someone decides to try to redo what you've done using the best approach, and they hit a wall because you never wrote down that you tried that and it didn't work for x reason. Writing up what you do helps keep your own thought process organized, so it's beneficial for you even if you never read what you wrote.

Definitely!

I didn't mean documentation at the code level - I believe well-written code is always better than docs - it should not be used to hide badly written code. I was talking about documentation like product requirements, meeting notes, decisionf and trade-offs, design etc.