Skip to content

Workbook Architecture Standard

Status and scope

This standard describes a recommended, not mandatory, tab pattern for Excel-based products in this venture, plus a set of structural principles that do apply broadly. A product should adopt the parts of this pattern that fit its complexity (see proportional complexity in ../strategy/product-philosophy.md) and can justify deviations in its own specification under products/<slug>/.

Not every product needs every tab below. Use only what the product's complexity justifies.

  1. Start Here — orientation: what the tool does, how to use it, links/navigation to the rest of the workbook.
  2. Instructions — more detailed usage guidance than fits on Start Here, if needed.
  3. Setup / Configuration — centralized settings (see configuration-standard.md).
  4. Primary Inputs — the core data the customer must provide.
  5. Supporting Inputs — secondary or optional inputs, kept visually distinct from primary inputs.
  6. Dashboard — summarized view of results (see dashboard-and-reporting-standard.md).
  7. Reports — printable or exportable output views.
  8. Reference Data — lookup tables, constants, and other data the calculations depend on but the customer doesn't directly edit.
  9. Calculations — intermediate calculation logic, separated from both inputs and outputs.
  10. Archive / History — where a product tracks change over time (e.g., historical snapshots), kept separate from live working tabs.

Structural principles

  • Customer-editable areas must be visually distinguishable from everything else. A customer should never have to guess whether a cell is meant to be typed into. See workbook-visual-design-standard.md.
  • Calculated cells must not appear editable. Formatting, cell protection, and visual styling should make clear that a cell holds a formula, not free text.
  • Inputs and formulas are not mixed casually within the same cell or table column. A column is either an input column or a calculated column, not situationally both.
  • Hidden calculation sheets must be documented. If a sheet is hidden to reduce clutter, its existence and purpose must be recorded in the product's specification, not left as an undocumented surprise.
  • Very-hidden sheets are avoided unless justified. Excel's "very hidden" sheet state (not accessible via the standard unhide UI) should be reserved for cases with a specific, documented justification (e.g., protecting internal lookup logic from accidental customer modification), not used by default.
  • Excel Tables and structured references are preferred over unstructured ranges for tabular data, to improve both formula readability and resilience to row/column insertion.
  • Named ranges follow a documented naming convention (defined per product in its specification), rather than ad hoc names.
  • Volatile formulas are minimized (e.g., OFFSET, INDIRECT, NOW, TODAY used sparingly and deliberately), since they can degrade recalculation performance and make behavior harder to reason about.
  • Microsoft 365 may be preferred as the baseline compatibility target for new products, since it provides the most current formula functions and dynamic-array behavior — but the actual baseline for a given product must be explicitly stated (see compatibility-standard.md).
  • Dynamic arrays are allowed when compatibility permits. They should not be avoided reflexively; they should be used when they improve the product and the stated compatibility baseline supports them.
  • Macros are not the default. A product should default to formula-only construction unless a macro provides a capability that can't reasonably be achieved without one, and any macro use must be documented and justified in the product specification.
  • Cross-version compatibility claims must be tested, not assumed. See compatibility-standard.md.
  • Print behavior must be specified and tested — print areas, page breaks, scaling, and headers/footers should be deliberately set, not left to Excel's defaults, and verified by an actual print/print-preview check.
  • Protection is a usability measure, not a security boundary. See protection-and-security-standard.md.
  • Accessibility does not rely on color alone. See accessibility-standard.md.

Report an issue about this page