> My favorite trick is to [...] actively enforce [...]
If active enforcement were an option, and it led to success, I don't imagine there would be a problem.
My favorite trick is to tell people really nicely they should write comments (preferrably doc comments on internally exported interfaces).
Yet, they don't. And so we're back to the dilemma:
If a significant percentage of competent programmers choose to not comment their code, or update the comments that are in the code, the comments will lie over time. And so it is probably better to not include them.
We haven't even reached the point in the conversation where we ask "But why is it you, dear competent programmers with decades of experience, think we should continue to minimize the amount of comments with good conscience?" or ask "Why is it, dear project managers, that we tolerate a total lack of communication through any other means than executable code?" And the answer is probably: Because a lot of autists produce a lot of valuable code, and they don't like to talk if they can avoid it, and we value their work and relay what they made to the wordy-word people.
> If people aren't reading your documentation it means they don't trust your documentation.
I don't trust your documentation unless there's alignment among developers. Alignment is a luxury you don't get in legacy shops.
Many of us "autists" may be of the opinion that the code IS the documentation and describing that in ambiguous natural language for some unspecified audience is just not very useful (and can be actively harmful). Use the source luke.
The documentation discussion tends to take for granted that documentation is automatically valuable, and more documentation there is, the better. I find well named and structured code and actually executable standalone examples are far more valuable for understanding a codebase than some by-rote restating of what the code already says.
If people don't add documentation to their PR, I add that documentation to the PR for them (under my own name as a separate commit), then land the code.
Do that often enough and people get the idea that documentation isn't optional.
If active enforcement were an option, and it led to success, I don't imagine there would be a problem.
My favorite trick is to tell people really nicely they should write comments (preferrably doc comments on internally exported interfaces).
Yet, they don't. And so we're back to the dilemma:
If a significant percentage of competent programmers choose to not comment their code, or update the comments that are in the code, the comments will lie over time. And so it is probably better to not include them.
We haven't even reached the point in the conversation where we ask "But why is it you, dear competent programmers with decades of experience, think we should continue to minimize the amount of comments with good conscience?" or ask "Why is it, dear project managers, that we tolerate a total lack of communication through any other means than executable code?" And the answer is probably: Because a lot of autists produce a lot of valuable code, and they don't like to talk if they can avoid it, and we value their work and relay what they made to the wordy-word people.
> If people aren't reading your documentation it means they don't trust your documentation.
I don't trust your documentation unless there's alignment among developers. Alignment is a luxury you don't get in legacy shops.