3 ms·
I think one of the most important features for documentation is that it needs to earn people's trust. If people expect that the docs won't be comprehensive or
by simonw 3y ago
I think one of the most important features for documentation is that it needs to earn people's trust.
If people expect that the docs won't be comprehensive or will be out-of-date, they won't use them.
This is why I'm so keen on documentation living in the same repo as the rest of the project. That way it can be kept up-to-date with the state of the code, through a policy where PRs are only merged when they include the relevant documentation updates.
Having that policy in place really helps people learn to both write and read the documentation.
- mike_hearn 3y agoI've done that and still do. It helps a bit, but only if your code reviewers are actually going to enforce the rule. It seems like most programmers simply don't like reading or writing documentation even though they can save large amounts of time for everyone by doing so. Certainly it's frustrating to be told e.g. "this thing we use can't do X" when how to do X is discussed in the thing's user guide, simply because someone didn't want to read it. I've had that experience before. Code reviews let you force the issue for a while but it's hard to scale. Getting other people to enforce the same rules via review is difficult. Many devs will be really strict about things like unit testing and make it a point of pride, but not at all strict at all about updating docs. Other devs will learn which reviewers let them avoid writing things in English and send reviews there preferentially, or find other ways to dodge it. Fixing this via training or policy turned out to be nigh-on impossible: many people simply will not change regardless of how many times you send a code review back for missing docs. Nor will they change even when their questions are constantly being answered by a link to the docs, which they don't take as "you should be embarrassed that I had to google that for you" but rather "hey here's a helpful link, you're welcome". Fundamentally there's a lack of shame about not reading things. It's not unique to software either. People ask questions answered by docs, or even by emails they just received, or they make bold assertions contradicted by docs they claim they've read, and when this is pointed out they just shrug it off in a way they wouldn't do if an obvious bug snuck through that should have been caught by testing. It's a cultural issue and needs to change, really. One fix I'm experimenting with at the moment is for a Linux kernel style hierarchy of reviewers where everyone gets their own repo and they merge upwards, so there's at least clear ownership and if someone is consistently letting docs rot that becomes apparent to the ultimate TL when they do a quick eyeball of big merges. It may also be worth experimenting with large language models. They could be given a change and asked, "given policy X, should this change have updated the documentation?" and if the LLM says yes then that gets flagged centrally for followup, for example.
- mike_hearn 3y agoI've done that and still do. It helps a bit, but only if your code reviewers are actually going to enforce the rule. It seems like most programmers simply don't like reading or writing documentation even though they can save large amounts of time for everyone by doing so. Certainly it's frustrating to be told e.g. "this thing we use can't do X" when how to do X is discussed in the thing's user guide, simply because someone didn't want to read it. I've had that experience before. Code reviews let you force the issue for a while but it's hard to scale. Getting other people to enforce the same rules via review is difficult. Many devs will be really strict about things like unit testing and make it a point of pride, but not at all strict at all about updating docs. Other devs will learn which reviewers let them avoid writing things in English and send reviews there preferentially, or find other ways to dodge it. Fixing this via training or policy turned out to be nigh-on impossible: many people simply will not change regardless of how many times you send a code review back for missing docs. Nor will they change even when their questions are constantly being answered by a link to the docs, which they don't take as "you should be embarrassed that I had to google that for you" but rather "hey here's a helpful link, you're welcome". Fundamentally there's a lack of shame about not reading things. It's not unique to the software world either. People ask questions answered by docs, or even by emails they just received, or they make bold assertions contradicted by things they claim they read that morning, and when this is pointed out they just shrug it off in a way they wouldn't do if an obvious bug snuck through that should have been caught by testing. It's a cultural issue and needs to change, really. It's possible AI can help here. Some people just don't want to sit down and read, but they'll ask questions, so an AI that reads the docs regularly could motivate people to write it. Or you could use them for code review enforcement by giving them changes and asking, "given policy X, should this change have updated the documentation?" and if the LLM says yes then that gets flagged centrally for followup, for example.
- Lutger 3y agoExactly. Good documentation is much harder than you'd think. I had similar policies. Also periodic reviews and especially during onboarding new devs I had them review the docs and make a list of missing points etc Its just as important to delete out of date topics. Wrong and stale info is costly, it decreases trust and sends people in wrong directions. edit: another obvious but surprisingly difficult thing to do is have everything in one system and make sure everything knows where to find it. Especially if your org is a bit bigger everybody will have their own systems and it'll be a big mess before you know it. But even so, within a single project I've often seen 3 to 8 'sources of truth', like trello tickets, images in onedrive, a word doc, markdown files, various propietary formats, pinnend posts in chat system, email archives, etc, etc.