1.5 Document Conventions

Go to 1. Introduction

The Crucible wiki uses consistent structural, terminology, linking, and writing conventions so readers can distinguish architectural concepts, implementation details, examples, requirements, and status statements.

Each major section uses a numbered namespace and a section overview page. Child pages repeat the displayed section number in their namespace.

Examples:

dido:02-crusible:01-introduction:start
dido:02-crusible:01-introduction:01-1-purpose:start

Every page includes a link to its parent page near the top. Section overview pages use an indexmenu block to display their child pages.

The shared Terms and Definitions annex controls the meaning of defined terms used in Crucible.

A page should link the first significant occurrence of a controlled term to its definition. Repeated occurrences on the same page normally remain unlinked unless another link materially helps the reader.

A Crucible page should not create a local definition when the shared annex already contains an applicable definition. When the current glossary does not contain a required term, the author should review the existing corpus before proposing a new entry.

Capitalization should follow the controlling glossary entry when a term refers to a defined Crucible concept. General uses of the same words may remain lowercase when they do not invoke the defined concept.

The shared References annex contains authoritative and supporting sources used by Crucible.

Pages should reuse an existing reference entry when one already identifies the applicable source. A new reference entry should be added when no suitable entry exists.

References should support factual, technical, legal, regulatory, standards-based, or product-specific statements. A reference does not replace the architectural explanation provided by the page.

Normative requirements use the following modal verbs:

• SHALL identifies a mandatory requirement
• SHALL NOT identifies a prohibition
• SHOULD identifies a recommendation
• SHOULD NOT identifies a discouraged approach
• MAY identifies a permitted option

Normative modal verbs appear in uppercase.

Descriptive, explanatory, tutorial, and status content should avoid normative modal verbs unless the page states a formal requirement.

Crucible pages use:

• Active voice where practical
• Present tense
• Explicit actors and responsibilities
• US English spelling
• The Oxford comma
• Short, focused paragraphs
• Unordered lists without terminal punctuation
• Defined terms consistently
• Precise distinctions among architectural intent, implemented capability, demonstrated capability, and roadmap capability

Pages should avoid:

• Ambiguous pronouns
• Unnecessary passive voice
• Unexplained acronyms
• Marketing language
• Unsupported claims
• Repetition of glossary definitions
• Mixing architectural requirements with implementation instructions
• Treating planned capability as current capability

Commands, paths, configuration fragments, and source examples appear in code blocks.

Examples illustrate a concept or workflow but do not establish a requirement unless the surrounding text explicitly identifies the example as normative.

Product names, command names, filenames, and option names should preserve their official spelling and capitalization.

Pages that describe capability availability should use the status model defined in 16.1 Status Model.

A page should distinguish among:

• Proven Live
• Implemented Capability
• Partially Implemented Capability
• Architectural Intent
• Roadmap Capability

The current implementation-status section controls claims about capability maturity when another page contains older or less-specific status information.

Each Crucible page ends with the following copyright statement:

----

<WRAP centeralign>
© 2026 Dido Solutions, Inc. and Jackrabbit Consulting, Inc.
</WRAP>