Skip to main content
ScaleMath

Plan the structure, gate the publish

The usual advice is to let structure emerge from small improvements. Real work has a scope, a reviewer and a date, so we plan up front and gate publication.

The usual advice about documentation is to avoid restructuring exercises, and instead make small, responsive improvements to whichever page you happen to be working on, letting the overall shape emerge.

That advice assumes the shape can be left to emerge. It is also how a library ends up organised around tickets, releases and search terms: every individual improvement is reasonable on its own, and the result is still a library nobody planned. Real work has a shape anyway. An agreed scope, a named reviewer, a date, and someone who needs to know what they are getting before it starts.

So we plan the structure up front, and we gate publication. This is a deliberate choice, not an oversight, and it is the single biggest practical difference between this method and the way documentation usually gets improved.

The cost of planning up front is that the plan is sometimes wrong. We accept that and handle it in review, rather than accepting the alternative cost, which is discovering the shape of a documentation project halfway through it.

Need this applied to your documentation?

We audit, restructure and write product documentation for B2B software companies.

Product documentation servicesRun a free documentation audit
ScaleMath
  • Full stack, senior team: you get us, not just one person that's good at one thing.
  • Your strategic partner: we're here to serve you. Get our input on strategy, product, customer experience, UX, and more.
  • We've helped renowned companies like:
AtarimAAWPWP Fusion