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.
This guide defines how all AOWIS pages should be written.
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
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.
3. Sentence Structure Guidelines
For Normative Text
- One requirement per sentence
- Avoid conjunctions unless logically necessary
- Avoid passive voice unless it improves clarity
- 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.
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.
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).
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. == Safety Boundaries == What the module MUST NOT override. == Data Model == Structured fields. == Offline Behavior == How the module behaves without connectivity. == Integration == How it interacts 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. 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)