3 ms·

One of the surprising difficulties of creating a good culture around documentation I found is getting people to actually read and use it. I guess the root cause

by Lutger 3y ago

One of the surprising difficulties of creating a good culture around documentation I found is getting people to actually read and use it. I guess the root cause of this is bad documentation itself, so developers come to not expect to find anything useful in there and just ignore it by default. I've often seen developers who spend hours fiddling on some detail that was clearly mentioned in the readme of the very same repository containing the code on which they are stuck, or who just failed to read the extensive documentation and proceed to 1) run the code and 2) call me for help. Furthermore, I've actually caught myself doing the same more than once. This led me to think that for a good documentation culture, the primary question should be: how are developers actually going to use and benefit from the docs? How documentation will get updated is the second question of importance, and writing documentation comes third.

mewpmewp2 3y ago
I admit, I rarely read documentation of anything, since I have no clue whether to trust it, so I will usually try to just follow my logical thought process of figuring out the solution or by trial and error. This also makes me bad myself at documentation, because if I don't use it I also feel internally that no one would read what I write in the first place also. Out of responsibility I will try to document shared things, but I never feel productive while doing that, I feel like I am just writing into a void.
- Cthulhu_ 3y ago
  > I rarely read documentation of anything, since I have no clue whether to trust it There's another big issue with documentation; it's often a write-and-forget thing. I'm confident every team or department should have a full-time documentation owner whose job it is to ensure documentation is up to date, maintained, and verified.
  - makeitdouble 3y ago
    That happens when you have legal requirement on the documentation. The same way you have an accountant peering over and keeping track of every transaction that happens in your company. Short of that you'll need to explain why the company is losing money because Jim didn't write a full explanation on why his "getUserIdOrNull" function returns null when the user id is not available.
  - MetaWhirledPeas 3y ago
    > I'm confident every team or department should have a full-time documentation owner whose job it is to ensure documentation is up to date, maintained, and verified. I'm not convinced this would work. Such a person wouldn't have time to be a subject matter expert at anything other than the documentation tools. They wouldn't understand what they were writing about.
zackees 3y ago
[dead]
kwanbix 3y ago
In my experience, not everybody is good at writing good documentation. I usually see software build by brilliant engineers, people much smarter than I at building software, and the documentation sucks. Not that is not there, but that is very difficult to understand. It is clear to me that you can be very smart at doing certain things (for example writing software) and suck at others (writing documentation).
BlargMcLarg 3y ago
Unfortunately, most cultures teach developers not to read. Between having barely any documentation, poor discoverability of said documentation, poor quality documentation, teaching people to 'talk at the first sign of trouble', it is only natural this is the outcome. Now we're stuck with both a chicken-and-egg problem at most places, while in places with decent documentation, many developers still come in not reading it, discouraging any significant upkeep of existing documentation.
ponyous 3y ago
I never start with documentation, but I find it immensely useful. Usually it starts with someone asking about something and you can just link them to the docs without having to talk to them.
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 ago
  I'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.
macintux 3y ago
You’re indirectly pointing to two ongoing problems with docs: discoverability and findability. Can you accidentally or purposefully find what you need to know?

by Lutger 3y ago

mewpmewp2 3y ago

I admit, I rarely read documentation of anything, since I have no clue whether to trust it, so I will usually try to just follow my logical thought process of figuring out the solution or by trial and error. This also makes me bad myself at documentation, because if I don't use it I also feel internally that no one would read what I write in the first place also. Out of responsibility I will try to document shared things, but I never feel productive while doing that, I feel like I am just writing into a void.

Cthulhu_ 3y ago
> I rarely read documentation of anything, since I have no clue whether to trust it There's another big issue with documentation; it's often a write-and-forget thing. I'm confident every team or department should have a full-time documentation owner whose job it is to ensure documentation is up to date, maintained, and verified.
- makeitdouble 3y ago
  That happens when you have legal requirement on the documentation. The same way you have an accountant peering over and keeping track of every transaction that happens in your company. Short of that you'll need to explain why the company is losing money because Jim didn't write a full explanation on why his "getUserIdOrNull" function returns null when the user id is not available.
- MetaWhirledPeas 3y ago
  > I'm confident every team or department should have a full-time documentation owner whose job it is to ensure documentation is up to date, maintained, and verified. I'm not convinced this would work. Such a person wouldn't have time to be a subject matter expert at anything other than the documentation tools. They wouldn't understand what they were writing about.

zackees 3y ago

[dead]

kwanbix 3y ago

In my experience, not everybody is good at writing good documentation. I usually see software build by brilliant engineers, people much smarter than I at building software, and the documentation sucks. Not that is not there, but that is very difficult to understand. It is clear to me that you can be very smart at doing certain things (for example writing software) and suck at others (writing documentation).

BlargMcLarg 3y ago

Unfortunately, most cultures teach developers not to read. Between having barely any documentation, poor discoverability of said documentation, poor quality documentation, teaching people to 'talk at the first sign of trouble', it is only natural this is the outcome. Now we're stuck with both a chicken-and-egg problem at most places, while in places with decent documentation, many developers still come in not reading it, discouraging any significant upkeep of existing documentation.

ponyous 3y ago

I never start with documentation, but I find it immensely useful. Usually it starts with someone asking about something and you can just link them to the docs without having to talk to them.

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 ago
I'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.

macintux 3y ago

You’re indirectly pointing to two ongoing problems with docs: discoverability and findability. Can you accidentally or purposefully find what you need to know?