AOWIS:Writing Style Guide/v1.0: Difference between revisions

Latest revision as of 01:29, 8 April 2026

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

Related

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)

@@ Line 2: / Line 2: @@
 ''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.