Comment by hinkley | Hacker News Reader

Comment by hinkley | Hacker News Reader

Parent Full thread

One of the things I've learned from many attempts to document internal processes at organizations, is that often the authors are least equipped to explain things.

They know too much, they often don't recognize how many pieces of assumed information they're injecting into their so-called explanations. You often get circular explanations in addition to circular reasoning and it can be off-putting.

A better use of time is to get someone who is just started to exhibit competence to write the docs. They won't assume the jargon, they can't assume deep knowledge, and because they're living right at the pain point they can be especially sympathetic. And if what they explain is dead wrong, this is your chance to correct a horrible misunderstanding before they get too far along. Pointing out the 'false friends' in a system early on can be pretty powerful. Educationally or as an opportunity for improving the system.

In other words, I'd encourage you to invite new people to contribute. Just keep an eye on what they do and be ready to jump in with corrections.

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.

> 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.

Totally 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.)

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

110% 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.

Is this a general tip you're giving, or is there specifically pieces of information you feel are being too opaque in the text at this point?

I'm just saying don't sweat people seeing it when it's not done yet. That's often enough exactly what you need.

(though maybe to clarify, that's not a subtle dig. I haven't read it yet, though I'm trying to get into Elixir so I'm bookmarking)

Can't speak for him but maybe both?

If both, we would certainly appreciate the feedback about which areas are considered unclear, in order to improve things further.

Can't people just remember what it was like to learn the things they know? They were all those newbies at one point.

Yes and no. Some of the struggles are fresher than others, and in some cases you do internalize things to the point they feel like a second nature.

The effort mentioned here of getting newer people to read the content and/or produce it is something I've done a lot in the past, and one of the ways I've used in on-boarding people as well. We (the co-authors of Adopting Erlang) tend to do it with topics where we don't know everything the other authors know, and provide feedback to each other about things that lack clarity.

I've also taught Erlang stuff in multiple places and started knowing some of the things people find confusing as a kind of pattern, which may get easier to address early on with time.

The thing that can never be done well, though, is predicting the things someone with an entirely different background from yours would find confusing; the context carried by their experience influences the things they understand and the information they extract from a text. Teaching to a functional programmer is different from teaching to a developer who has done OO their entire career. Teaching to someone doing front-end work is going to be a different experience from teaching to someone doing mobile or back-end work. The same may often extend to sociological, economical, or cultural factors as well.

All of this means that each teaching experience has new surprises as well and you can't just cover them by thinking very hard. Frequent reviews, both technical and from editors can help, though, along with your own experience when teaching.

No. What you're describing is the problem people have when teaching/providing insight/responding to questions online. They all use their current understanding and apply it to the question not assuming the other person has no knowledge of the subject.

Haven't you ever seen someone ask a question online that had a "newbie" answer that is generally correct, only to have a ton of people flood your response with all the caveats ignoring who their audience actually is. The default for most people is to use your current knowledge.

This struggle is often referred to as the "Curse of Knowledge"

https://en.wikipedia.org/wiki/Curse_of_knowledge

Becoming familiar with a system makes you forget what was and what was not obvious. I experience this with myself. Once I've learned something well, then I can find it hard to explain it to someone else. I find it best if I write down assumptions that got corrected or unclear things as I encounter them.

I've seen this in other disciplines, and if anything to worse degree. I've witnessed situations where the old masters can't talk to the journeymen, and the new masters can barely talk to the beginners. You learn by watching and whatever the people a couple years ahead of you can decipher for you.

To make matters worse, what often happens is that the instructors believe they have taught something, and they don't witness the actual learning take place, so they continue in their belief in their practices.

As someone who did a lot of professional training and love to teach complete beginners it’s definitely possible but it’s not intuitive and it’s a lot of conscious work.

Reply on news.ycombinator.com