> 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.

> 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_fence https://en.m.wikipedia.org/wiki/Wikipedia:Chesterton%27s_fen...