8 ms·
In my experience, the best documentation usually starts with a section called "Concepts" or something similar. Beyond some simple floor of complexity, starting
by dcolkitt 7y ago
In my experience, the best documentation usually starts with a section called "Concepts" or something similar.
Beyond some simple floor of complexity, starting by elucidating the high-level concepts you're dealing with is really important to convey understanding. Too many docs jump straight from the introduction into the technical minutiae. The doc writer often takes for granted all the implicit mental models they've built up from repeatedly hacking on the underlying system. Without those mental models, the technical details are just meaningless facts that the user's never going to retain.
Great documentation starts by carefully explaining the core concepts not just from the system, but from the problem domain itself. This builds up a common vocabulary that allows for precision, non-ambiguity, and clarity throughout the rest of the documentation.