[cbondurant]

I feel like a lot of documentation falls into this kind of style, where the motivation behind design is not communicated, just the design itself. Sometimes it's because the documentation writer doesn't want to leak internal details to the end user (closed source libraries are an especially bad source of this). Sometimes it's that the writer is too close to the project, and is struck by the curse of knowledge (can't properly identify which details are actually self-evident, and which are only obvious because they already know them).

Another example of why technical writing is difficult, I think.

[saghm]

I worked on a team where the responsibility of maintaining the onboarding guide was always passed to whoever joined right after they finished going through it (with the current maintainer being the "onboarding buddy" of the new team member and passing the torch at the end). The rationale was that the longest-tenured members of the team would be the most likely to accidentally rely on implicit knowledge when updating it and forget to put in something that wouldn't be obvious to a newcomer, and the person who had needed to learn the processes from scratch most recently would be the most likely to notice gaps like that (and could reach out to the rest of the team to have the gaps explained to them so they could fill them in).

I always liked that mindset, and it helped teach me the important lesson that sometimes being the person who asks very basic questions because I don't understand things can make me valuable to the teams I work on. There are certainly times when the answer makes me go "oh, duh!", and I feel a little sheepish, but the feeling doesn't last very long, and no one has ever held it against me, whereas the times when it leads somewhere interesting and potentially to better documentation for people coming after me are far more frequent and memorable to everyone involved.

This isn't to say that the burden should fall on the ones who are reading the documentation rather than writing it, but to encourage people who are in the position of being frustrated and confused to take advantage of those moments, because they can make you very valuable to your team in addition to helping you learn. If you're on a team that operates in good faith, the burden for documenting things well can be shared, and in the long run it will matter less who's job it is to keep it updated and more about whether everyone is contributing however they can to maintain the quality (and if you're on a team that operates in bad faith, you have my permission to keep quiet and do whatever you can to get through that experience, not that you need it from me!)