dido:02-crusible:01-introduction:01-05-document-conventions:start

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
dido:02-crusible:01-introduction:01-05-document-conventions:start [2026/08/01 04:11] – removed - external edit (Unknown date) 127.0.0.1dido:02-crusible:01-introduction:01-05-document-conventions:start [2026/08/01 04:11] (current) – ↷ Page moved and renamed from dido:02-crusible:01-introduction:01-05-document-conventions to dido:02-crusible:01-introduction:01-05-document-conventions:start nick_dido
Line 1: Line 1:
 +====== 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>