Why writing small docs is a game changer

In software development, there has been multiple instances of people advocating or discussing opting for small commits. This makes sense for a number of reasons, but there are also writers in my company advocating for small docs. And it makes sense.

As technical writers, we aim to make information clear, accessible, and actionable. But there’s another factor to consider: how the size of a document impacts its effectiveness. Small, focused docs can save time, reduce stress, and make the review process much smoother. Here’s why small docs are a smart approach and how to create them.

The benefits of small docs

Smaller docs aren’t just easier to write—they make life better for everyone involved. Here’s why:

• Quicker reviews
  Small docs fit into short time slots, making it easier for reviewers to give feedback promptly. Compare finding five minutes for a small doc to setting aside 30 minutes for a sprawling one.
• Thorough feedback
  A focused document reduces the risk of reviewer fatigue, leading to better feedback. Reviewers can dig into the content without feeling overwhelmed or missing key details.
• Lower stakes if rejected
  If a small doc is off track, less time is wasted compared to investing hours into a lengthy draft that gets scrapped.
• Easier integration with other work
  Small docs are less likely to conflict with parallel efforts or overlap with other teams’ work.
• Simpler to polish
  Revising and refining smaller docs is easier than wrestling a massive document into shape.
• Unblocked workflows
  By submitting focused sections for review, you can keep drafting other parts of a project without waiting.
• Flexible abandonment
  If a project changes direction, it’s easier to set aside a small, self-contained doc than untangle a long one.

What makes a doc “small”?

The key is focusing on one self-contained idea. Think of it as solving one part of a puzzle at a time. Here are some guidelines:

• Minimal argument
  A small doc should address just one topic or change, like a single feature or a focused proposal. Err on the side of writing too small rather than too large.
• Self-contained context
  Include all the necessary background so the reviewer doesn’t need to dig into other docs for clarity.
• Not overly simplified
  Avoid making the doc so small that its implications are unclear. For example, if you’re proposing a new API, include usage examples to show how it works.

For most cases, docs under three pages are a good target. Longer docs may need to be broken into smaller parts, depending on the complexity and the number of teams involved.

Avoid blocking yourself during reviews

Small docs shine when they’re part of a productive workflow. But waiting for reviews can stall progress. In my experience, reviews are always the bottleneck and the bane of documentation. Here’s how to keep things moving:

• Write in parallel
  Work on multiple small docs at the same time, so you always have something to do while waiting for feedback.
• Collaborate with reviewers
  Consider in-person reviews or pair writing to speed up the process. Sometimes it is easier for busy people if you book a 20 min slot in their calendar and go over a doc together.
• Draft background docs first
  If your main doc relies on understanding existing functionality, create a separate background doc to set the stage. This background doc could even be used for multiple documents. Think of it as a concepts guide or an overview of how everything fits together and why it is important.

What if you can’t make it small?

Occasionally, a doc may seem too complex to break down. In these cases:

• Start with background
  Writing a background doc first can help simplify the main proposal by establishing a shared understanding.
• Discuss with teammates
  Brainstorm with others to find ways to split the work into smaller, manageable pieces.
• Get reviewer consent
  If a large doc is unavoidable, inform reviewers in advance and set expectations for a longer review process.
• Review by sections
  Make it easy for you and them to keep a consistent workflow, review small sections at a time, and when everything is approved, you can then publish the full document. This may feel slower but can be a game changer if you want to have better reviews.

Even in rare cases where large docs are necessary, focusing on clarity and breaking down ideas wherever possible will save time in the long run.

Managing the challenges of many small docs

A potential downside of writing small docs is the risk of information becoming fragmented. Without careful organization, multiple small docs can lead to confusion or difficulty finding the right information. To mitigate this:

• Organize effectively
  Use clear categories, tags, and libraries to connect related documents. Information architecture is key for this, and I should probably deep dive into information architecture techniques and strategies in other posts in the future.
• Link related content
  Include links to background docs, proposals, or other relevant resources. Improves discoverability and helps when you are defining certain storytelling. Specially if your documentation tool supports pagination.
• Maintain doc hygiene
  Regularly clean up outdated docs, deprecate irrelevant ones, and ensure your documentation set stays cohesive. Easier said than done, but it is part of keeping the documentation lights on.

Final thoughts

Writing small docs isn’t just about reducing word count, it’s about focusing your ideas, streamlining collaboration, and creating a better experience for reviewers (and for you, in the long run). While it takes practice to break down big ideas into smaller parts, the effort pays off in faster reviews, clearer communication, and less stress.

Next time you start a big writing project, ask yourself how you can make it smaller. You’ll likely find the results more manageable and impactful.

What do you think?

Have you tried writing smaller docs? What challenges or successes have you had? Share your experiences—I’d love to hear how you approach writing concise and effective documentation!