Skip to content

Editorial Calibration

This page records the harmonization pass so future contributors have a durable calibration target.

Recurring Weaknesses Found

  • Weak pages named taxonomy and support tier before showing an artifact.
  • Several pages treated field extraction as enough and did not identify semantic authority.
  • Failure and ambiguity often appeared as generic boilerplate rather than page-specific observer risk.
  • Visuals sometimes described architecture instead of teaching timing, authority, arbitration, or reconstruction.
  • Source notes was present but too often felt detached from the teaching claim.
  • Implementation-contract language leaked into reader-facing endings.
  • Template-complete field notes sometimes looked more mature than their page-specific teaching depth justified.

Strongest Pages After Harmonization

Page Calibration value
CAN Arbitration, cadence, and transport-vs-meaning separation.
DBC Semantic authority and plausible false values.
MIL-STD-1553 Centralized authority and transaction-shaped observation.
UART Framing hypothesis and timing recovery.
ARINC 429 Label context, SSM validity, and cadence-based avionics observation.
Modbus RTU Polling authority and register-map dependence.

Recurring Conceptual Wins

  • Bytes rarely explain themselves.
  • Timing is evidence, not metadata decoration.
  • A passive observer forms state hypotheses, not omniscient truth.
  • Description files and register maps are authorities with provenance, not neutral utilities.
  • A valid checksum, parity bit, CRC, or status word proves only a bounded structural claim.

Visual Guidance

Prefer compact field, timing, transaction, arbitration, and observer-reconstruction diagrams. Remove any diagram that does not clarify one of these concepts:

flowchart LR artifact["Artifact"] --> timing["Timing"] timing --> authority["Authority"] authority --> ambiguity["Ambiguity"] ambiguity --> observer["Observer hypothesis"]

Contributor Anti-Patterns

  • Starting with governance tier instead of artifact.
  • Copying standards-like prose instead of paraphrasing inspection structure.
  • Naming a signal without naming the authority that defines it.
  • Treating public tutorials as normative standards.
  • Adding planned API sections that read like product promises.
  • Using a diagram because the page feels empty.

Future Page-Writing Rules

  1. Start from one concrete synthetic artifact.
  2. Decode it in front of the reader.
  3. Name timing assumptions before state claims.
  4. Name semantic authority before engineering units.
  5. Include a page-specific failure and ambiguity section.
  6. Keep implementation posture short.
  7. Group sources by role and distinguish official material from teaching cross-checks.
  8. Do not reproduce large copyrighted standards tables or normative language.
  9. Label thin but useful pages draft-structure-only until their artifact, timing, ambiguity, and observer sections are genuinely page-specific.