AOWIS:Writing Style Guide/v1.0

A consistent voice for a technical, engineering-grade standard.

---

Related

• AOWIS:AI_Usage_Guide
• AOWIS:Contributor_Guide_Internal
• AOWIS:Contributor_Guide_External

---

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)