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)