AOWIS Internal Contributor Guide (v1.0)

Guide for AOWIS staff contributing directly to wiki pages, modules, and research.

1. Purpose

This guide defines how AOWIS staff contribute content directly to the wiki while ensuring:

• Consistent naming and page structure
• Traceable versioning
• Conformance to AOWIS writing standards
• Safe and auditable edits

2. Audience

Intended for AOWIS staff with direct write access to the wiki. Includes:

• Engineers
• Software developers
• Research staff
• Technical documentation team

3. Contribution Types

Staff may create or update:

1. Normative content (Standards pages)
2. Explanatory content (Concepts, Architecture)
3. Module documentation
4. Research pages
5. Reference pages

All content must follow the AOWIS Writing Style Guide.

4. Namespaces

Use the appropriate namespace for all contributions:

• [[Standard:|Standard]] – normative requirements
• [[Concepts:|Concepts]] – explanatory content
• [[Architecture:|Architecture]] – system design
• [[Modules:|Modules]] – module-level specs
• [[Data:|Data]] – schemas, measurements
• [[Operations:|Operations]] – operational guidance
• [[AOWIS:|General]] – contributor guides, research guides, admin

Note: Research content lives in the same domain namespaces; do not create a separate Research namespace.

5. Page Creation and Updates

New pages

• Check if a page already exists.
• Use descriptive names per naming rules.
• Add "/vX.X" for versioned content (research pages, new modules, major updates).

Updating existing pages

• Minor edits: update the latest version directly.
• Substantive changes:
  • Copy the previous version to a new "/vX.X" page.
  • Edit the new version.
  • Update the base page redirect to the new version.
  • Add a "Versions" section listing prior versions.

6. Versioning

• Use the "/vX.X" suffix for versioned pages.
• Increment for substantive changes (v1.0 → v1.1).
• Base page always redirects to the latest version.
• Previous versions remain immutable.
• Include a "Versions" section at the top of each versioned page.

7. Editing Workflow

• Minor edits: directly on the latest version page.
• Major edits: create a new "/vX.X" version, update redirect, update "Versions" section.
• Use the Edit summary to describe changes.
• Use Talk pages for discussion if needed.

8. Writing Standards

Follow the Writing Style Guide:

• Normative text: precise, testable, uses RFC 2119 keywords.
• Explanatory text: human-centered, contextual, uses examples.
• All measurements must include units.
• Terms must match definitions exactly.

9. Templates and Tools

• Use pre-defined templates for modules, research forms, and version headers.
• See Module Template for module pages.
• Use a proper Version Header for version tracking. Include:
  • Version: v1.0
  • Date: 2026-04-01

10. Human Interaction

• Describe human actions as explicit inputs.
• Avoid vague statements (e.g., "operator can intervene if needed").

11. Linking and Integration

• Use pipe syntax for human-readable links: [[Page_Name|Page Name]].
• Maintain consistency with existing page structure.
• Add cross-links to related pages as needed.

12. Review and Approval

• Normative changes must be reviewed by a technical lead.
• Explanatory updates should be reviewed for clarity and correctness.
• Research findings should be verified before inclusion.

13. Change Log

• Every versioned page must include a version and date.
• Document major changes in the edit summary.
• Reference Change Log & Versioning format.

End of AOWIS Internal Contributor Guide (v1.0)