3 ms·

The problem for me is that it over-estimates my competence. We've been told for years that it's demeaning to do the opposite and underestimate or over-explain,

The problem for me is that it over-estimates my competence. We've been told for years that it's demeaning to do the opposite and underestimate or over-explain, so people may have been erring too far in this direction. We've also seen a lot of "the burden of communication lies on the communicator, not the listener," (quotes indicate paraphrasing) but this may also have led to overcorrection on the part of some listeners. It's often impossible to predict what knowledge level and cultural background one's readers will have, so somehow we have to find a middle ground and ask that everyone mutually assume good faith and put in some effort to understand the other party, both when communicating and when reading.

MattGaiser 5y ago
My solution to that is just an abundance of links. Here is a tutorial I wrote: https://dev.to/mattgaiser/how-to-debug-an-office-js-manifest-file-4bi9 https://dev.to/mattgaiser/how-to-debug-an-office-js-manifest... I tried to just link to anything that might require more info. If you know how to do it, great, don't click the link. Otherwise, what you need is right there.
chousuke 5y ago
I think good documentation should help the user build a mental model. Keep explanations to the point in general, but insert short reminders about previous concepts (with cross-references to s detailed explanation) to keep them in the reader's mind. Some redundancy in documentation is a plus. If you always include at least a summary of what the user is expected to know, it lets the user read the documentation nonlinearly without getting completely lost when they hit an unfamiliar concept.
Kalium 5y ago
I've found myself addressing the issue with a section at the top of documentation about the expected reader. I can get quite explicit about what the reader is expected to know, include links to relevant backgrounders, and warn that any reader who does not meet the requirements may have trouble. This way, when someone ignores the section and comes to me in incomprehension of a document they were not expected to understand, I can ask them what was unclear about the "About This Document" section. Although that's probably optimistic about how often people read documentation.

MattGaiser 5y ago

My solution to that is just an abundance of links. Here is a tutorial I wrote: https://dev.to/mattgaiser/how-to-debug-an-office-js-manifest-file-4bi9 https://dev.to/mattgaiser/how-to-debug-an-office-js-manifest... I tried to just link to anything that might require more info. If you know how to do it, great, don't click the link. Otherwise, what you need is right there.

chousuke 5y ago

I think good documentation should help the user build a mental model. Keep explanations to the point in general, but insert short reminders about previous concepts (with cross-references to s detailed explanation) to keep them in the reader's mind. Some redundancy in documentation is a plus. If you always include at least a summary of what the user is expected to know, it lets the user read the documentation nonlinearly without getting completely lost when they hit an unfamiliar concept.

Kalium 5y ago

I've found myself addressing the issue with a section at the top of documentation about the expected reader. I can get quite explicit about what the reader is expected to know, include links to relevant backgrounders, and warn that any reader who does not meet the requirements may have trouble. This way, when someone ignores the section and comes to me in incomprehension of a document they were not expected to understand, I can ask them what was unclear about the "About This Document" section. Although that's probably optimistic about how often people read documentation.