Skip to main content

Quality Bar for New Content

Purpose​

This guide should read like architecture synthesis, not notes copied from books or docs. Use this quality bar before adding or accepting new content.

Minimum chapter structure​

A strong chapter should include most of the following:

  • why the topic matters
  • core mental model
  • decision framework
  • implementation patterns
  • anti-patterns or failure modes
  • verification checklist
  • metrics or scorecard
  • exercises
  • source lens

Tutorials and capstones can use milestone structure, but they still need decision points, evidence, and review criteria.

Advanced chapter structure​

For core architecture chapters, prefer this stronger structure:

  • problem framing with user/business/operational risk
  • constraints and assumptions
  • decision model with rejected alternatives
  • implementation patterns by team maturity
  • failure modes and incident examples
  • verification plan with pre-release and production signals
  • ownership and operating model
  • completed or partially completed artifact
  • exercise that produces portfolio evidence
  • source lens with stable and fast-moving dependencies

Quality rules​

  • Write original architecture guidance derived from sources.
  • Prefer route, component, boundary, and workflow examples over abstract slogans.
  • Include failure modes; advice without failure modes is usually too shallow.
  • Include verification; architecture must be observable or reviewable.
  • Connect technical decisions to user, business, or operational risk.
  • Avoid framework cheerleading.
  • Avoid long verbatim source text.
  • Avoid placeholder sections.

Depth checklist​

  • Does the content help a senior engineer make a better decision?
  • Does it name the cost of the recommendation?
  • Does it explain when not to use the pattern?
  • Does it include concrete review prompts?
  • Does it produce an artifact a learner or team can use?
  • Does it connect to related chapters?
  • Does it have enough detail to be practiced?
  • Does it include a completed example or point to one?
  • Does it distinguish low-risk, medium-risk, and high-risk contexts?
  • Does it name the owner of ongoing operation after launch?
  • Does it describe how production feedback changes future architecture?

Publishing checklist​

  • Build passes.
  • npm run docs:check passes or has reviewed warnings for short chapters, placeholder markers, missing frontmatter/title/sidebar position, duplicate slugs, broken local markdown links, and missing practice/review/source sections.
  • Frontmatter has title, sidebar_position, and optional slug.
  • No unfinished placeholder markers or placeholder copy remains.
  • No tracking parameters remain in links.
  • No broken markdown conversion artifacts remain.
  • New claims about unstable platforms were verified against current primary sources.
  • Current-source claims are reflected in current-research-synthesis-2026 or the chapter source lens.