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.