Four kinds of documentation (divio.com)

Article summary

The article discusses the importance of understanding that there are four different types of documentation: tutorials, how-to guides, technical reference, and explanation. Each type serves a distinct purpose and requires a unique approach to creation. The author argues that recognizing this distinction can significantly improve documentation quality. The article also mentions a video presentation on the topic and provides an outline of a documentation system.

Main themes

• documentation types
• documentation quality
• technical writing
• software development
• communication

What commenters say

• Good documentation is crucial for the success of a software project, but it is often neglected.
• Auto-generated documentation can be useless and even misleading if not done properly.
• Writing good documentation requires a dedicated effort and a passion for clear communication.
• Some developers are uncomfortable with writing prose and may avoid it, leading to poor documentation.
• Documentation can become outdated quickly if not maintained properly, and this can be a significant problem.
• The quality of documentation can be improved by treating it as an integral part of the development process, rather than an afterthought.
• The use of narrative and descriptive language in documentation can make it more effective and useful for users.
• The lack of good documentation can be a result of prioritizing new features and bug fixes over documentation and testing.