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
Example:
The Field Controller MUST enforce pump protection locally. 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
3. Sentence Structure Guidelines
3.1 For Normative Text
- One requirement per sentence
- Avoid conjunctions unless logically necessary
- 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
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. == 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. == 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.
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)
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. Prohibited Terms in Normative Text
The following terms MUST NOT be used:
- reliable
- efficient
- robust
- intelligent
- adequate
- sufficient
- appropriate
12. Versioning
Rules:
- Each page MUST include a version identifier
- Changes to normative requirements MUST increment the version
13. Examples of Good AOWIS Style
Normative
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)
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)