Skip to main content
ScaleMath

Resolve conflicting principles

Two pairs of principles contradict each other in ordinary use. A method that does not rank them produces a library that contradicts itself.

Two collisions come up constantly. A writer resolves them by feel, which is fine once and inconsistent across 400+ articles. Resolve them this way instead.

One authoritative answer against reduce unnecessary navigation

Repeat material only when it is short, stable, and unlikely to change on its own schedule. A required permission, a default value or a one-line prerequisite can be repeated. A procedure, an explanation or a reference table cannot.

The test is maintenance. If the repeated material would need updating in two places the next time the product changes, link to it instead.

Sufficiently self-contained against one primary job

Include the explanation when the user cannot complete the step without it. Link the explanation when the user could complete the step without it but would understand the outcome better with it.

If the explanation runs longer than the step it supports, it belongs on its own page.

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