News for hackers. Stuff that matters.
Re:Adopting Erlang by hinkley on Tuesday October 29, 2019 @01:18PM (#21389608)
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.

Re:Adopting Erlang by K0SM0S on Wednesday October 30, 2019 @05:19PM (#21402875)
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.