3 ms·
Beyond the Four-Document Model
- layer8 4y agoConceptual overviews is what I most commonly miss in documentation. Or sometimes if they are there, they are so high-level that it remains unclear what exactly the project or product is bringing to the table compared to other similar ones, and/or the essential underlying mechanisms remain unclear.
- justinludwig 4y agoI like the thinking behind this article, but it seems to me that the additional types the author brings up are all just specialized versions of the four primary documentation types: - Conceptual Overviews: High-level "explanations" (broader instead of deeper). - Examples (and case studies): "How-to guides" that focus on more narrowly-specific use cases instead of more general or common ones. - FAQs: "Reference" -- what readers want from FAQs are short concise answers, ideally with links to further details. - Troubleshooting: "How-to guides" that focus on fixing common problems. - Best practices: Opinionated "explanations" that focus just on best practices -- the best "best practices" guides explain why, not just what.
- actuallyalys 4y agoI mostly agree (although I might quibble with how you categorized FAQs and best practices), but I think these subtypes are significant enough that discussing them separately is worth it.