View source for AOWIS:Research Form Guide/v1.0

{{DISPLAYTITLE:AOWIS Research Form Guide (v1.0)}}

''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
* 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'''

----

== 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:Writing Style Guide|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

---

== 9. Versioning and Updates ==

* Every research form MUST include a <code>version</code> parameter (e.g., v1.0, v1.1)
* Increment the version for substantive changes (v1.0 → v1.1)
* When a version is incremented:
** The previous page is left unchanged (archived in place)
** A new page is created for the updated version
** The new page SHOULD include a “Previous Versions” or “Version History” list linking to all prior versions
* Use categories consistently to allow search and filtering across versions

== 10. Templates ==

* [[AOWIS:Reasearch Form Template v1.0 with explanations]]
** [[AOWIS:Reasearch Form Template v1.0]]

----

''End of AOWIS Research Form Guide (v1.0)''