Jump to content

AOWIS Research Form Guide (v1.0)

From AOWIS


Guide for contributing research forms in AOWIS-compliant style.

This guide explains how engineers and technical developers should structure, write, and submit research forms for the development of the AOWIS open standard. It ensures clarity, traceability, and auditability for all technical investigations related to water and agricultural infrastructure systems.

1. Purpose of the Research Form Guide

Research forms in AOWIS:

  • Record technical analysis, design options, and engineering decisions
  • Maintain consistency across engineering contributors
  • Enable traceability from problem to recommendation
  • Support audit and standardization processes

This guide specifically covers research forms for engineers and software developers. Other research guides, e.g., for farming crews or field staff, will be created separately in the future.

2. Audience

Research forms using this guide are intended for:

  • Engineers designing system components
  • Software developers evaluating protocols or modules
  • Internal AOWIS technical teams investigating new technologies
  • Optional: External technical partners reviewing design decisions

Implications:

  • Language MUST be precise and technical
  • Sections MUST be filled for clarity and traceability
  • Terminology MUST follow AOWIS definitions
  • Versions MUST be tracked
  • Focus is on engineering feasibility, reliability, and implementability; operational instructions for field staff are outside the scope of this guide

3. Structure of a Research Form

Each research page SHOULD use the following sections:

3.1 Required Sections

  • Title — Clear, descriptive title of the research topic
  • Version — Format: v1.0, v1.1, etc.
  • Context — Background information, origin of research, prior discussions
  • Problem — Specific technical challenge or requirement being addressed
  • Options Considered — List of candidate solutions
  • Findings — Observations, pros/cons, evidence for each option
  • Conclusion — Recommended approach and rationale

3.2 Optional Sections

  • Implementation Notes — Guidance for developers to implement the chosen approach
  • Open Questions — Unresolved issues or further technical investigation
  • References — Supporting technical documents or studies
  • Author / Contributor — Name(s) and affiliation(s)

---

4. Writing Style Rules

Follow AOWIS style conventions:

  • Use precise, technical, unambiguous language
  • Use short, declarative sentences
  • Avoid marketing, emotional, or vague language
  • Keep paragraphs concise
  • Normative statements (e.g., “MUST” requirements) SHOULD NOT appear in research forms unless providing direct guidance for the standard

---

7. Best Practices

  • Start each research page with a descriptive title
  • Provide clear technical context; reference discussions or sources
  • Evaluate options objectively; include pros/cons with measurable or technical criteria
  • Keep conclusions concise and directly traceable to findings
  • Document open questions for further technical investigation
  • Use categories for easier navigation and retrieval
  • Increment the version whenever the research is updated

---

8. Examples

Example 1: Normative-Explanatory Hybrid

{{ResearchForm
 | title = Communication Methods for Offline-First Controllers
 | version = v1.0
 | context = Discussion originated from Matrix room #architecture
 | problem = Controllers must operate reliably with intermittent connectivity
 | options = MQTT; HTTP polling; LoRa; Local mesh networks
 | findings = MQTT requires stable broker connectivity; HTTP polling is simple but inefficient; LoRa offers low bandwidth but limited throughput
 | conclusion = MQTT with local buffering is preferred for AOWIS reference implementations
 | open_questions = Synchronization strategies; Conflict resolution in offline scenarios
 | author = Jane Doe, AOWIS Engineer
}}

---

Example 2: Lightweight Form

{{ResearchForm
 | title = Low-Power Sensor Communication
 | version = v1.0
 | context = Field deployment testing
 | problem = Minimize power consumption for battery-operated sensors
 | options = LoRa; BLE; Zigbee
 | findings = LoRa has lowest power usage; BLE is simpler but drains faster; Zigbee requires mesh maintenance
 | conclusion = LoRa is recommended for remote sensors
}}

---

9. Versioning and Updates

  • Every research form MUST include a `version` parameter
  • Increment the version for substantive changes (v1.0 → v1.1)
  • Maintain previous versions in page history
  • Include notes in `implementation_notes` for major revisions

End of AOWIS Research Form Guide (v1.0)

Retrieved from "http://aowis.afriticgroup.com/index.php?title=AOWIS:Research_Form_Guide/v1.0&oldid=125"