3 ms·

> "Know thy audience" With end users I find it very hard to predict technical knowledge, which can vary by orders of magnitude and often include misinformation

> "Know thy audience" With end users I find it very hard to predict technical knowledge, which can vary by orders of magnitude and often include misinformation or the completely wrong focus, and which users themselves estimate unreliably. For that reason, unless I know better, I tend to aim low - better to tell them extra than to make it incomprehensible. There seems to be ego tied up in it for users; if you aim to high, they won't admit that they don't understand, and if you aim too low they might get insulted: I get complaints, often politely implicit, that they feel condescended to. How does one communicate the basics without sounding condescending? I have some sense of it, of course, but I don't feel that I know the trick.

ASinclair 8y ago
One thing you can do is state assumed knowledge at the start of your documentation. Then you can provide references to other documents in case the reader doesn't know the prerequisites for the doc.
kaycebasques 8y ago
> if you aim to high, they won't admit that they don't understand, and if you aim too low they might get insulted Yes, it's a tricky balance. Another way to frame the importance of this topic is: if you explain too much, you make your readers wade through a flood of information, which slows them down; if you explain too little, the doc is unusable. > How does one communicate the basics without sounding condescending? ASinclair's suggesting of adding a prerequisite section to your doc is a good strategy. It also helps to develop "content types" where you describe in general what types of information you include in each type of content. For example, suppose you define 3 content types: overview, tutorial, and reference. * The overview contains conceptual explanations. * The references contain everything you might possibly need to know about a given topic. * The tutorial contains task-based, step-by-step workflows. Rather than explaining concepts in the tutorial, you link them to the overviews. Rather than going into the nitty-gritty about a topic, you link to the reference. You probably get the idea from here. Each content type contains clearly-defined amounts and types of information. Rather than jamming all the information into a tutorial, you link off to the overview and reference. The people that need more information can follow the links to learn more. The people that don't need it get a straightforward tutorial without extraneous info.

ASinclair 8y ago

One thing you can do is state assumed knowledge at the start of your documentation. Then you can provide references to other documents in case the reader doesn't know the prerequisites for the doc.

kaycebasques 8y ago

> if you aim to high, they won't admit that they don't understand, and if you aim too low they might get insulted Yes, it's a tricky balance. Another way to frame the importance of this topic is: if you explain too much, you make your readers wade through a flood of information, which slows them down; if you explain too little, the doc is unusable. > How does one communicate the basics without sounding condescending? ASinclair's suggesting of adding a prerequisite section to your doc is a good strategy. It also helps to develop "content types" where you describe in general what types of information you include in each type of content. For example, suppose you define 3 content types: overview, tutorial, and reference. * The overview contains conceptual explanations. * The references contain everything you might possibly need to know about a given topic. * The tutorial contains task-based, step-by-step workflows. Rather than explaining concepts in the tutorial, you link them to the overviews. Rather than going into the nitty-gritty about a topic, you link to the reference. You probably get the idea from here. Each content type contains clearly-defined amounts and types of information. Rather than jamming all the information into a tutorial, you link off to the overview and reference. The people that need more information can follow the links to learn more. The people that don't need it get a straightforward tutorial without extraneous info.