How to prepare documentation?

Summary

In this video, Frederick shares insights on how to prepare effective documentation for both technical and user guides. He emphasizes the importance of clear structure, categorizing documentation into guides (step-by-step tutorials) and overviews (high-level system understanding). Key tips include making documentation searchable by aligning terminology with users' search habits, maintaining relevance through regular updates, and organizing content in small, focused articles. Frederick also highlights the significance of using version control, having a review process, and ensuring that documentation is easy to maintain and up-to-date, ensuring long-term usability.

Takeaways

• 😀 Clear distinction between two types of documentation: guides (task-focused) and overviews (concept-focused).
• 😀 Guides are step-by-step documents designed to help users execute specific tasks quickly.
• 😀 Overviews are high-level introductions that provide a general understanding of the system, aimed at high-level stakeholders.
• 😀 Never mix guide documentation with overview documentation to avoid confusion and frustration for users.
• 😀 Documentation should be easy to find by users, using clear entry points and search functionality.
• 😀 Ensure that documentation is structured around the terminology and jargon commonly used by the target audience.
• 😀 Smaller, focused documents are better than large, redundant ones, as they are easier to maintain and update.
• 😀 Use Markdown for documentation because it’s universally supported and offers version control for easy updates.
• 😀 Avoid excessive use of images and videos in documentation as they require constant updates, which complicate maintenance.
• 😀 Implement a regular review process where team members rotate responsibility for maintaining and updating the documentation.
• 😀 Ensure that documentation is regularly updated to remain relevant, and track the last review date and responsible team members for transparency.

Q & A

What are the two primary types of documentation mentioned in the script?

The two primary types of documentation mentioned are guides and overviews. Guides provide step-by-step instructions for executing a task, while overviews offer high-level explanations and concepts about the system.

Why is it important to distinguish between guides and overviews in documentation?

It is important to distinguish between guides and overviews because they serve different purposes. Guides help users execute specific tasks with clear, actionable steps, while overviews are meant to introduce higher-level concepts to those seeking to understand the system or domain.

How does the script suggest documentation should be structured for optimal searchability?

For optimal searchability, documentation should be structured with clear, consistent jargon and terminology that aligns with how users will search for information. It’s important to think like the user and anticipate the search terms they might use to find relevant content.

What is the significance of using markdown files for documentation, according to the speaker?

Markdown files are preferred because they are universally supported, easy to maintain, and provide version control, allowing for quicker updates and better tracking of changes. This makes documentation more adaptable and easier to keep current.

Why does the speaker recommend using small, focused documents instead of large ones?

Small, focused documents are easier to maintain and update. Instead of duplicating information across many files, smaller articles can be linked together, ensuring the documentation remains concise, clear, and less prone to errors.

How does the speaker propose ensuring that documentation stays up-to-date?

The speaker suggests implementing a regular review process, where a different team member is assigned each month to check and update the documentation. This ensures that the information remains accurate and relevant over time.

What is the potential issue with using videos in documentation, according to the script?

The issue with using videos is that they can quickly become outdated if the system or interface changes. Keeping videos up-to-date can be more challenging, and they may not reflect the current state of the system, leading to confusion.

How does the speaker compare writing good documentation to being a good teacher?

The speaker compares writing good documentation to teaching because both aim to communicate complex concepts in a clear and understandable way. Good documentation should help users execute tasks or understand systems, similar to how a teacher helps students learn and grasp new material.

What role does search functionality play in documentation?

Search functionality in documentation is essential because it allows users to quickly find the information they need. Whether through a main entry point or a search bar, documentation should be easy to navigate and locate specific content.

What is the importance of a documentation review process, and how does it benefit the team?

The documentation review process ensures accuracy and relevance. It benefits the team by promoting knowledge sharing, as team members must engage with the documentation to identify outdated content or errors. It also creates accountability by linking the document to the reviewer’s name, ensuring ongoing maintenance.