CONTRIBUTING - AtlasOfLivingAustralia/documentation GitHub Wiki

Contributing to the Living Atlases Documentation Wiki

This document defines the editing spec and governance rules for this wiki (specially for AI agents).

Core Principles

  1. Never break existing URLs. Do not rename tracked files. GitHub wiki links and external references depend on exact filenames.
  2. No content invention. Only improve what exists or link to what already exists in the codebase.
  3. Safety first for language edits. English corrections apply to body text only โ€” never to anchor names, internal wiki links, code blocks, or example URLs.
  4. Deprecations over deletions. Mark obsolete content with a legacy notice; do not remove it.

File Naming

  • New pages: kebab-case, descriptive, e.g. My-New-Topic.md
  • No spaces in filenames
  • No special characters except hyphens and dots

Folder Structure

/                              โ† tracked wiki pages (public)
drafts/                        โ† unfinished pages not yet published
old-probably-safe-to-delete/   โ† obsolete material, binaries, historical exports
img/                           โ† images used by tracked pages
files/                         โ† downloadable files referenced in pages

What goes in drafts/

  • Pages under active writing that are not ready to be linked from any public page
  • Notes and internal KB files (e.g. agents.md)
  • Workshop presentations and internal docs
  • Do no commit drafts

What goes in old-probably-safe-to-delete/

  • Binary exports (PDF, PPTX, HTML exports of presentations)
  • Video files (.webm, .mp4, .gif) โ€” link to external hosting instead
  • Confluence exports
  • Loose scripts and tooling not part of the documentation
  • Duplicate files with wrong extensions
  • Do no commit this directory

Marking Deprecated / Legacy Content

When a section or page describes an approach that is no longer recommended, add a blockquote notice at the top of the section, without removing the existing content:

> โš ๏ธ **Legacy:** This section describes the legacy `biocache-store` backend.
> For new installations, use [pipelines](Pipelines-process-overview) instead.

For a full page that is legacy, for instance, in the case of the backend:

> โš ๏ธ **Legacy page:** This page describes a workflow that is no longer recommended
> for new deployments. It is kept for reference for existing installations.
> See [Pipelines process overview](Pipelines-process-overview) for the current approach.

Known legacy areas (as of 2025)

Component / topic Status Current replacement
biocache-store (Scala) Legacy backend pipelines
ala-demo playbook Obsolete la-toolkit
CAS 5.x auth stack Still in active use Install via la-toolkit (recommended); OIDC is a supported auth protocol on top of CAS (since ala-install 2.1.14) โ€” CAS components remain deployed
Confluence exports in conflu/ Historical reference only โ€”

Recommended Install Method

The primary recommended installation method is currently the la-toolkit that uses ala-install.

When writing or updating installation documentation:

  • Mention la-toolkit first as the recommended path
  • The underlying ansible (ala-install + generator-living-atlas) can be described as the mechanism la-toolkit automates
  • Do not recommend ala-demo playbook for new deployments

English Style

  • Plain English, technical but accessible to non-native speakers
  • Spell out acronyms on first use per page
  • Avoid emoji in body text (sidebar and home page are OK)
  • Consistent heading capitalisation: sentence case preferred (## Configure your regions, not ## Configure Your Regions)

Safe Change Checklist

Before editing a tracked .md file:

  • Change is in body text only
  • No anchor names changed (e.g. ## My Section โ†’ anchor is #my-section)
  • No internal wiki links changed (e.g. [Troubleshooting](/AtlasOfLivingAustralia/documentation/wiki/Troubleshooting))
  • No code blocks modified unless factually wrong
  • No example URLs modified
  • If marking something deprecated, legacy notice added at section top

KB-assisted accuracy verification

When verifying whether documented claims (versions, paths, commands, deprecations) are still accurate, use the living-atlas-kb MCP (collection la_toolkit_kb, ~470k documents indexed from ALA/LA source repos). Query it with query_ala_kb before making a factual change.

Rule: no factual edit without KB evidence cited in drafts/kb-audit-findings.md (relevance score + source path). The KB orients โ€” it does not decide; human review is still required.

Severities used in the findings log: error-factual ยท version-outdated ยท dead-link ยท gap ยท mark-legacy.

Commit conventions

One commit per file changed. Commit message format:

docs(<filename-without-extension>): <short description>

Examples:

docs(LA-Quick-Start-Guide): add la-toolkit as primary install method
docs(Jenkins-For-Biocache-Store): mark page as legacy biocache-store
docs(CONTRIBUTING): add initial editing spec