Skip to main content

Documentation

Instructions that can be followed consistently to attain expected standards enable the ability to derive deterministic outcomes when planning for the future.

Documentation is not just about recording information - it's about enabling others to succeed with your product or project/business. The best documentation anticipates needs and provides clear paths to solutions, that evolves with your product and business.

Mantra

If it isn't written down it didn't matter

Context​

Principles​

Documentation exists to help readers achieve their goals efficiently and effectively. The foundation of world-class documentation rests on several key principles:

Reader-Centric Approach

  • Focus on what the reader needs to accomplish rather than simply describing features
  • Understand your target audience's technical expertise and requirements
  • Structure content around user goals and tasks rather than system architecture

Quality Over Quantity

  • Write less, but write it well - avoid sprawling documentation
  • Focus on documenting what you can maintain long-term
  • Remove outdated or incorrect documentation proactively

Best Practices for Creation​

Planning and Structure

  • Start with a clear outline based on user needs
  • Use consistent templates and formatting
  • Organize content logically with clear navigation
  • Create documentation that can scale as your product grows

Writing Style

  • Use simple, clear language and avoid technical jargon
  • Keep sentences under 25 words for better readability
  • Write in an active, direct voice
  • Front-load important information in each section

Visual Enhancement

  • Break up text with headings, lists, and white space
  • Include relevant screenshots, diagrams, and videos
  • Use code formatting for technical content
  • Create visual aids for complex processes

Maintenance Strategy​

Regular Updates

  • Schedule periodic reviews of documentation
  • Track versions and changes systematically
  • Remove or update outdated content promptly
  • Collect and incorporate user feedback

Team Collaboration

  • Assign clear ownership and responsibilities
  • Establish review processes with subject matter experts
  • Use collaborative tools for team input
  • Create style guides for consistency across contributors

Technical Considerations​

Accessibility

  • Ensure documentation is easily searchable
  • Implement proper indexing and tagging
  • Make content accessible across different devices
  • Provide clear navigation paths

Tools and Integration

  • Use version control for documentation
  • Implement automated documentation where possible
  • Choose appropriate documentation tools for your needs
  • Integrate documentation with existing workflows

Documentation Types​

Essential Documents

  • Project overview and goals
  • User guides and tutorials
  • Technical specifications
  • API documentation
  • Troubleshooting guides
  • Release notes
  • FAQs (but use sparingly)

Checklist​

Proof of value to establish/maintain trust and credibility.

  1. Who is this for?
  2. What do they need to get done?
  3. Who are the experts? What proof?
  4. How is this valuable? What proof?
  5. What concepts do they need to understand?
  6. What logical steps?
  7. What can go wrong?
  8. Have you said what you need to say?
  9. Where to next? What is this related to? What don't you know?

Content Structure

  • What don't you know/understand?
  • What does this relate to
  • Where can your learn more

Tools and Templates​

Invest in templates and checklists to drive consistency and make it easier to get started. Investing in the right tools has potential for a payback in cutting out firefighting and support efforts to save time and money when customers can help themselves.

Leverage tools and protocols to establish a one way flow inspiration to a single source of the truth.

  1. Fork and update a process or document
  2. Create a change request or meeting agenda
  3. Write an email or chat referencing process or document defining action
  4. Use chat to agree amendments and action plan

Choose verbal or video if sensitive topic or team members that have a low teamwork index rating.