3 ms·
I honestly also think it is worth mentioning introductions as an essential part. I somewhat disagree that it is outside the scope of a scheme of documentation.
by janekm 6y ago
I honestly also think it is worth mentioning introductions as an essential part. I somewhat disagree that it is outside the scope of a scheme of documentation.
An introduction to both the system goals and overall architecture provide essential context for the rest of the documentation, and can even provide the scaffold to structure it around.
It is all too common for writers of documentation (deeply embedded in the project) to forget that the person reading the documentation may have no clue what the whole system is trying to achieve (especially so in public-facing documentation... how many times do you see a link on HN to a documentation page with no explanation of what "a BUZZY GRAPHEME WRANGLER" actually is?).
Also... by your analogy, I am fairly certain that a guide to writing a technical book would dedicate a fairly considerable amount of space to the topic of a good introduction ;)
- DanieleProcida 6y agoI don't disagree about the importance of introductions. I can't count the number of times I've looked at the home page of documentation for some product and it has felt like stumbling into a teenagers' conversation conducted entirely incomprehensible references, slang and in-jokes. An introduction needs to say what the thing is, what it does and why someone might want to use it. Usually that can be expressed in a few sentences. I don't really see it as a mode of documentation in the way that the four components I describe are. I wouldn't worry too much though. The framework isn't intended as a "do this, all this and nothing but this or you're doing it wrong" final statement on the art of documentation. It's more a tool for thinking about what you are writing, for whom, and how you can best write it for them. It's to be used however someone finds it useful.