AOWIS Writing Style Guide (v1.0)
A consistent voice for a technical, engineering-grade standard.
AOWIS is a technical standard for water and agricultural infrastructure in low-resource environments. Its writing style MUST be clear, unambiguous, implementable, accessible, and consistent.
1. Two-Tone Writing Model
AOWIS uses two distinct writing tones depending on the purpose of the page.
A. Normative Tone (Engineering Style)
Used in:
- Standard:
- Safety rules
- Controller responsibilities
- Data models
- Protocols
- Compliance requirements
Characteristics:
- Precise and unambiguous
- Short, declarative sentences
- No storytelling or metaphors
- No adjectives unless measurable
- Uses RFC 2119 keywords (MUST, SHOULD, MAY)
- One requirement per sentence
- Statements MUST be testable and uniquely identifiable
Example:
REQ-FC-001: The Field Controller MUST enforce pump protection locally. REQ-FC-002: Remote systems MUST NOT override safety-critical decisions.
B. Explanatory Tone (Conceptual / Contextual)
Used in:
- Concepts:
- Real-world constraints
- Human-in-the-loop
- Offline-first rationale
- Paper operation
Characteristics:
- Descriptive and contextual
- Human-centered
- Explains why the standard works this way
- Uses examples where helpful
Example:
In many rural regions, water infrastructure must operate under unstable power conditions. AOWIS therefore emphasizes offline-first operation and local autonomy.
2. Normative Language Rules (RFC 2119)
AOWIS uses the following keywords:
- MUST — absolute requirement
- MUST NOT — absolute prohibition
- SHOULD — strong recommendation
- SHOULD NOT — discouraged practice
- MAY — optional feature
Rules:
- Use these words only for normative statements
- Always write them in ALL CAPS
- Never soften them (e.g., “should probably”, “must ideally”)
- Never mix them with narrative tone
- Each normative statement MUST be testable through observation, measurement, or inspection
- Each normative requirement MUST include a unique identifier
3. Sentence Structure Guidelines
3.1 For Normative Text
- One requirement per sentence
- Normative sentences SHOULD contain a single logical condition
- Prefer active voice
- Passive voice MAY be used only when the actor is irrelevant
- Avoid ambiguous terms (“adequate”, “sufficient”, “appropriate”)
- Prefer measurable or observable criteria
Bad:
The pump should run long enough to fill the tank.
Good:
The pump SHOULD run until the tank level sensor reports FULL.
3.2 For Explanatory Text
- Use narrative flow
- Provide context
- Use real-world examples
- Use human-centered language
- Keep paragraphs short
Example:
Operators may act as sensors by reporting tank levels manually when electronic sensors fail.
3.3 Failure Conditions
Normative text MUST define behavior under failure conditions where relevant.
Failure conditions include:
- Power loss
- Sensor failure
- Communication loss
- Actuator malfunction
Each defined failure condition MUST specify:
- Detection method
- Required system behavior
- If a failure condition is not applicable, explicitly state "Not Applicable"
4. Terminology Rules
AOWIS uses:
- Simple, concrete nouns
- Consistent naming across namespaces
- Definitions before usage
Avoid:
- Buzzwords
- Marketing language
- Vague abstractions
- Synonyms that create ambiguity
Example: Use Field Controller, not “local device”, “embedded unit”, or “microcontroller”.
5. Page Structure Templates
A. Normative Page Template (Standard:)
== Purpose == Short description of what this section defines. == Requirements == List of MUST/SHOULD/MAY statements, each with a unique ID. == Definitions == Terms used in this section. == Notes == Non-normative clarifications (optional).
Rule:
- All normative statements MUST appear only in the "Requirements" section
- All other sections MUST be considered non-normative unless explicitly stated
B. Explanatory Page Template (Concepts:)
== Overview == High-level explanation. == Real-World Context == Why this concept matters. == AOWIS Approach == How the standard addresses the issue. == Examples == Optional, illustrative.
C. Module Page Template (Modules:)
== Purpose == What the module covers. == Inputs == Sensors, human inputs, data sources. == Outputs == Actuators, logs, decisions. == States == Operational states (e.g., IDLE, ACTIVE, FAULT). == State Transitions == Conditions for state changes. == Safety Boundaries == What the module MUST NOT override. == Data Model == Structured fields. == Offline Behavior == Behavior without connectivity (see rules). == Logging == Requirements for event and fault logging. == Integration == Interaction with Field/Farm/HQ controllers.
6. Tone Consistency Rules
Always:
- Write as if the document will be used for certification
- Assume the reader is technical but not necessarily an engineer
- Prioritize clarity over elegance
- Use short paragraphs
- Use headings generously
Never:
- Use humor
- Use metaphors
- Use emotional language
- Use marketing language
- Use ambiguous qualifiers (“robust”, “smart”, “intelligent”)
7. Audience Model
AOWIS is written for:
- Engineers
- Technicians
- NGOs
- Government agencies
- Researchers
- Field operators
Implications:
- Normative text MUST be precise
- Explanatory text MUST be accessible
- Examples MUST be realistic
- Assumptions MUST reflect low-infrastructure environments
8. Human Interaction Rules
Human actions MUST be described as explicit inputs.
Example:
The Operator MAY input tank level via manual entry.
Each human input MUST specify:
- Input method (e.g., button, SMS, paper entry)
- Validation rules
- Timeout or expiry behavior (if applicable)
Avoid:
The operator can intervene if needed.
9. Units and Measurements
Rules:
- All measurable values MUST include units
- Time MUST be expressed in:
- seconds (s)
- minutes (min)
- hours (h)
- Numbers SHOULD be written as numerals
- Avoid vague expressions such as "quickly", "immediately", "shortly"
10. Terminology Consistency
Rules:
- Terms MUST match their Definitions exactly
- A term MUST NOT be redefined with a different meaning across pages
11. Logging Requirements
The system MUST log:
- State transitions
- Fault conditions
- Manual overrides
- Sensor failures
Each log entry MUST include:
- Timestamp
- Source
- Event type
12. Offline Behavior Rules
Offline behavior MUST:
- Not depend on external systems
- Preserve safety constraints
- Define data synchronization behavior upon reconnection
13. Prohibited Terms and Patterns
The following words MUST NOT be used in normative text:
- reliable
- efficient
- robust
- intelligent
- adequate
- sufficient
- appropriate
The following patterns MUST NOT be used:
- Multiple requirements in a single sentence
- Hidden requirements in explanatory text
- Undefined terms in normative statements
14. Versioning and Backward Compatibility
Rules:
- Each page MUST include a version identifier
- Changes to normative requirements MUST increment the version
- Changes that break backward compatibility MUST:
- Increment the major version
- Document migration requirements
15. Conformance
A system is compliant with AOWIS if:
- All applicable MUST requirements are satisfied
- No MUST NOT requirements are violated
- Deviations from SHOULD requirements are documented and justified
- Each requirement MUST be uniquely identifiable
16. Examples of Good AOWIS Style
Normative
REQ-FC-001: The Field Controller MUST continue operating during network outages.
Explanatory
Because many rural regions experience unstable connectivity, AOWIS requires all safety-critical logic to run locally.
Hybrid (allowed in Architecture pages)
REQ-FC-002: The Field Controller MUST enforce pump protection locally. This ensures safe operation even when the Farm Controller is offline.
End of AOWIS Writing Style Guide (v1.0)