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)