The article "What nobody tells you about documentation" details how to write manuals for software, covering various components, their purposes, content, scope, and roles in simplifying the documentation process.
Types of Documentation.
Tutorial.
- Example: README.
- Target Audience: Beginner.
- Objective: To learn.
- Purpose: Practical + Educational.
Applying Best Practices:
- Simplify your software's entry point for any user (setup and installation details should be included).
- Organize into multiple tasks, suitable for beginners with simple instructions.
- Ensure the content is straightforward to reward users with knowledge securely.
- Maintain full functionality to foster confidence in learners.
Avoiding Missteps:
- Only include necessary explanations to avoid complexity.
- Keep tutorials concise by avoiding unnecessary details.
How-to Guides.
- Example: How to print an integer.
- Target Audience: Intermediate.
- Objective: Goal achievement.
- Purpose: Practical + For professional use.
Applying Best Practices:
- Ensure the guide is fully functional (include test cases if applicable).
- Provide a clear, search-friendly heading for better visibility.
- Create flexibility to account for slight variations in user needs.
Avoiding Missteps:
- Refrain from linking to API documentation excessively.
- Simplify content if installation or setup steps are not necessary at this level.
Explanation.
- Example: API Documentation.
- Target Audience: Experienced Users.
- Objective: Detailed Understanding.
- Purpose: Educational.
Applying Best Practices:
- Present documentation as code-based content, ideally auto-generated for consistency and accuracy.
- Provide practical examples where necessary to illustrate tough cases or advanced features.
- Maintain a consistent structure for enhanced readability.
Avoiding Missteps:
- Focus on technical aspects; avoid explaining design decisions unless they are crucial for understanding.
- Do not guide users towards achieving a specific goal (focus on how-to guides).
Reference Documents.
- Example: White Paper.
- Target Audience: Advanced Experts.
- Objective: Informational.
- Purpose: Deep and Comprehensive Understanding.
Applying Best Practices:
- Include design decisions, including alternatives for clarity.
- Provide historical context to deepen understanding.
- Present good practices and discuss or explore detailed contents.