[RandallBrown]

Documentation doesn't suck because companies aren't using wikis right.

Documentation sucks because it's hard/impossible to do well. Every change to the code can trigger cascading changes in documentation and there's no compiler to tell you which things need to change.

[joncp]

Exactly.

If we can't even keep the README up to date, when that's in the same repo as the change, how on earth are we going to be disciplined enough to go update the docs.

And the occurrence of the word "disciplined" hints at the real reason: it's a lot less fun to write docs than write code, so we don't unless we're forced to by circumstances or by management.

[CobsterLock]

dont most enterprise languages have built in docs that do a basic type check? I'm thinking of something like JavaDocs and MS Docs for C#, that at the very least have built in typing for explicit references to objects. But i do see the breakdown quickly happening when you informally reference concepts. I have been trying to push for getting as much documentation inside the actual code as possible and auto-generating a doc site using Doxygen or something similar. Mostly i want this because the documentation is closely related to the code. But we got stuck because other teams in the company want to use Confluence or some other wiki

[RandallBrown]

I don't know about most, but things like JavaDocs are certainly pretty common.

That's not really what we're talking about here though. Like you said, it's the concepts and informal stuff that's the problem.

I've found autogenerated stuff to only be marginally more helpful than just reading the code in the first place.