Designing for Maintainability

👉 Writing Tip #4: Add some personality

Key points in this video

A good documentation workflow makes maintaining easy, and creates an overall pleasant experience for the maintainers.

Some problems we might need to solve when designing for maintainability:

  • Proximity: The docs live far from the codebase, making it easier to forget.
  • Speed: The process is time-consuming.
  • Complexity: Complicated processes make the docs harder to maintain.
  • Quality control: No checks on the output can lead to inconsistent or incorrect output.
  • Learning curve: Too many things to learn for a new maintainer.
  • Feedback loop: Difficulty to preview the output before deploy makes the workflow slower and more inefficient.

The aim is to keep these in mind when designing our workflow, and pick tools and approaches that can help solve them.

Complete and Continue