AOWIS:Writing Style Guide/v1.0 - Revision history

Samuel at 01:29, 8 April 2026

2026-04-08T01:29:28Z

← Older revision		Revision as of 01:29, 8 April 2026
Line 6:		Line 6:
	; Related		; Related
	* [[AOWIS:AI_Usage_Guide]]		* [[AOWIS:AI_Usage_Guide]]
			* [[AOWIS:Contributor_Guide_Internal]]
			* [[AOWIS:Contributor_Guide_External]]
	----		----

Samuel at 00:38, 8 April 2026

2026-04-08T00:38:21Z

← Older revision		Revision as of 00:38, 8 April 2026
Line 2:		Line 2:

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

			----
			; Related
			* [[AOWIS:AI_Usage_Guide]]
			----

	AOWIS is a technical standard for water and agricultural infrastructure in low-resource environments.		AOWIS is a technical standard for water and agricultural infrastructure in low-resource environments.

Samuel: Samuel moved page AOWIS:Writing Style Guide to AOWIS:Writing Style Guide/v1.0

2026-04-01T03:45:47Z

Samuel moved page AOWIS:Writing Style Guide to AOWIS:Writing Style Guide/v1.0

← Older revision		Revision as of 03:45, 1 April 2026
(No difference)

Samuel at 22:30, 31 March 2026

2026-03-31T22:30:55Z

← Older revision		Revision as of 22:30, 31 March 2026
Line 29:		Line 29:
	* Uses RFC 2119 keywords (MUST, SHOULD, MAY)		* Uses RFC 2119 keywords (MUST, SHOULD, MAY)
	* One requirement per sentence		* One requirement per sentence
	* Statements MUST be testable		* Statements MUST be testable and uniquely identifiable

	Example:		Example:
	<pre>		<pre>
	The Field Controller MUST enforce pump protection locally.		REQ-FC-001: The Field Controller MUST enforce pump protection locally.
	Remote systems MUST NOT override safety-critical decisions.		REQ-FC-002: Remote systems MUST NOT override safety-critical decisions.
	</pre>		</pre>

Line 78:		Line 78:
	* Never mix them with narrative tone		* Never mix them with narrative tone
	* Each normative statement MUST be testable through observation, measurement, or inspection		* Each normative statement MUST be testable through observation, measurement, or inspection
			* Each normative requirement MUST include a unique identifier

	----		----
Line 85:		Line 86:
	=== 3.1 For Normative Text ===		=== 3.1 For Normative Text ===
	* One requirement per sentence		* One requirement per sentence
	* ~~Avoid conjunctions unless logically necessary~~		* Normative sentences SHOULD contain a single logical condition
	* Prefer active voice		* Prefer active voice
	* Passive voice MAY be used only when the actor is irrelevant		* Passive voice MAY be used only when the actor is irrelevant
Line 130:		Line 131:
	* Detection method		* Detection method
	* Required system behavior		* Required system behavior
			* If a failure condition is not applicable, explicitly state "Not Applicable"

	----		----
Line 159:		Line 161:

	== Requirements ==		== Requirements ==
	List of MUST/SHOULD/MAY statements.		List of MUST/SHOULD/MAY statements, each with a unique ID.

	== Definitions ==		== Definitions ==
Line 215:		Line 217:

	== Offline Behavior ==		== Offline Behavior ==
	Behavior without connectivity.		Behavior without connectivity (see rules).

			== Logging ==
			Requirements for event and fault logging.

	== Integration ==		== Integration ==
Line 267:		Line 272:
	The Operator MAY input tank level via manual entry.		The Operator MAY input tank level via manual entry.
	</pre>		</pre>

			Each human input MUST specify:
			* Input method (e.g., button, SMS, paper entry)
			* Validation rules
			* Timeout or expiry behavior (if applicable)

	Avoid:		Avoid:
Line 283:		Line 293:
	** minutes (min)		** minutes (min)
	** hours (h)		** hours (h)
			* Numbers SHOULD be written as numerals
	Avoid vague expressions such as:		* Avoid vague expressions such as "quickly", "immediately", "shortly"
	* quickly
	* immediately
	* shortly

	----		----
Line 299:		Line 306:
	----		----

	== 11. ~~Prohibited Terms in Normative Text~~ ==		== 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

			----

	~~The following terms MUST NOT be used:~~		== 13. Prohibited Terms and Patterns ==

			The following words MUST NOT be used in normative text:
	* reliable		* reliable
	* efficient		* efficient
Line 310:		Line 340:
	* sufficient		* sufficient
	* appropriate		* appropriate

			The following patterns MUST NOT be used:
			* Multiple requirements in a single sentence
			* Hidden requirements in explanatory text
			* Undefined terms in normative statements

	----		----

	== 12. Versioning ==		== 14. Versioning and Backward Compatibility ==

	Rules:		Rules:
	* Each page MUST include a version identifier		* Each page MUST include a version identifier
	* Changes to normative requirements MUST increment the version		* 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

	----		----

	== 13. Examples of Good AOWIS Style ==		== 16. Examples of Good AOWIS Style ==

	=== Normative ===		=== Normative ===
	<pre>		<pre>
	The Field Controller MUST continue operating during network outages.		REQ-FC-001: The Field Controller MUST continue operating during network outages.
	</pre>		</pre>

Line 335:		Line 383:
	=== Hybrid (allowed in Architecture pages) ===		=== Hybrid (allowed in Architecture pages) ===
	<pre>		<pre>
	The Field Controller MUST enforce pump protection locally.		REQ-FC-002: The Field Controller MUST enforce pump protection locally.
	This ensures safe operation even when the Farm Controller is offline.		This ensures safe operation even when the Farm Controller is offline.
	</pre>		</pre>

Samuel at 22:25, 31 March 2026

2026-03-31T22:25:39Z

Show changes

Samuel at 03:07, 18 March 2026

2026-03-18T03:07:23Z

← Older revision		Revision as of 03:07, 18 March 2026
Line 1:		Line 1:
	= AOWIS Writing Style Guide (v1.0) =		{{DISPLAYTITLE:AOWIS Writing Style Guide (v1.0)}}

	''A consistent voice for a technical, engineering‑grade standard.''		''A consistent voice for a technical, engineering‑grade standard.''

Samuel: Created page with "= 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 pa..."

2026-03-18T03:05:38Z

Created page with "= 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 pa..."

New page

= 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:
<pre>
The Field Controller MUST enforce pump protection locally.
Remote systems MUST NOT override safety‑critical decisions.
</pre>

=== 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:
<pre>
In many rural regions, water infrastructure must operate under unstable power conditions.
AOWIS therefore emphasizes offline‑first operation and local autonomy.
</pre>

----

== 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:
<pre>
The pump should run long enough to fill the tank.
</pre>

Good:
<pre>
The pump SHOULD run until the tank level sensor reports FULL.
</pre>

=== For Explanatory Text ===
* Use narrative flow
* Provide context
* Use real‑world examples
* Use human‑centered language
* Keep paragraphs short

Example:
<pre>
Operators may act as sensors by reporting tank levels manually when electronic sensors fail.
</pre>

----

== 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:) ===
<pre>
== 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).
</pre>

=== B. Explanatory Page Template (Concepts:) ===
<pre>
== Overview ==
High-level explanation.

== Real-World Context ==
Why this concept matters.

== AOWIS Approach ==
How the standard addresses the issue.

== Examples ==
Optional, illustrative.
</pre>

=== C. Module Page Template (Modules:) ===
<pre>
== 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.
</pre>

----

== 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 ===
<pre>
The Field Controller MUST continue operating during network outages.
</pre>

=== Explanatory ===
<pre>
Because many rural regions experience unstable connectivity, AOWIS requires all safety‑critical logic to run locally.
</pre>

=== Hybrid (allowed in Architecture pages) ===
<pre>
The Field Controller MUST enforce pump protection locally.
This ensures safe operation even when the Farm Controller is offline.
</pre>

----

''End of AOWIS Writing Style Guide (v1.0)''