1.5 Document Conventions [Dido Solutions, Inc Wiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 1.5 Document Conventions ======

[[dido:02-crusible:01-introduction:start|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.

===== Page Structure =====

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

Examples:

<code>
dido:02-crusible:01-introduction:start
dido:02-crusible:01-introduction:01-1-purpose:start
</code>

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

===== Terminology =====

The shared [[dido:99_annexes:annex-b-terms-and-definitions:start|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.

===== References =====

The shared [[dido:99_annexes:annex-c-references:start|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 Language =====

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.

===== Writing Style =====

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

===== Code, Commands, and Examples =====

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.

===== Status Statements =====

Pages that describe capability availability should use the status model defined in [[dido:02-crusible:16-implementation-status-and-roadmap:16-1-status-model:start|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.

===== Copyright =====

Each Crucible page ends with the following copyright statement:

<code>
----

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

----

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