5 ms·
This is gospel for teachers / learners. Well put. There's such as thing as too verbose, but it usually comes from writing stuff in the wrong kind of document:
by K0SM0S 7y ago
This is gospel for teachers / learners. Well put.
There's such as thing as too verbose, but it usually comes from writing stuff in the wrong kind of document: there is always a place for in-depth explanation, and there is a place for terseness to the point of familiarity.
One last thing: if your topic has a jargon of its own, a particular meaning to words, introduce these as early on as possible, and be excellent in consistency throughout docs (in addition, consider a definition link/info widget for each such term on its first occurence in any document, letting people 'jump right in' to any section/article). If you are going to force people to re-wire their brain to suit your particular vocabulary, you should maintain 'immersion' at all times.
If find this especially true in not-so-well-defined paradigms such as OOP when approached by various programming languages. You need a "map of terminology" more than anything else to quickly grasp how to use language XYZ.
- tasogare 7y ago> You need a "map of terminology" more than anything else to quickly grasp how to use language XYZ. Exactly why I hate Brew with passion. In the doc you find: formula, bottle, cask instead of package and... no idea what the others mean. I have no time to learn and remember the mapping, which exists for no other reason than the author trying to be cool.
- K0SM0S 7y agoTotally agreed! I think Brew will eventually be remembered as "this bad way of entering the topic of interest", like BASIC for programming, or a learning js / web programming through a framework first. It's teaching you the wrong way, making you almost illiterate about pm when you enter the real thing (here Linux/UNIX world, or Python after BASIC, vanilla web concepts, etc.)
- hinkley 7y agoI've found that a glossary helps, especially if there's a link to at document that talks about that concept. People who are bored or curious can pull on the thread at their own pace.
- K0SM0S 7y ago110% agreed. Anything that helps 'lateral' access to a knowledge base is helpful, because you don't need to go through all the bottom-up (learning) or top-down (prior knowledge) to explore and reach a given problem space. You can simply 'cheat' directly to 'stage N'. Once there, you might be missing key information: principles above you, terminology and base config below; this is where a glossary (hyperlinked automatically ideally) is a life-saver. Follow 1-2-3 links and you've got the gist, back to 'stage N' to the next step, rinse and repeat. When documentation is badly done, this approach may result in endless circular references, feeling 'trapped' at or around 'stage N' — you explore that stage all you want but gain no understanding of how it fits into the whole. But when it's well executed, such documentation is a treat — RHEL comes to mind as being very practical to use in that regard, for a rather complex/deep doc base.