IMPROVEMENT PLAN - AtlasOfLivingAustralia/documentation GitHub Wiki

Living Atlases Documentation Wiki — Improvement Plan

Created: 2026-04
Status: Active
Spec: See CONTRIBUTING.md

Context

This wiki is the primary technical documentation for the Living Atlases (LA) platform, used by GBIF nodes and ALA adopters worldwide. Over time it has accumulated:

  • Untracked draft files mixed in with published pages
  • Legacy content (especially biocache-store era) without deprecation notices
  • Binary files (videos, PDFs, exports) that don't belong in a wiki repo
  • Underrepresentation of la-toolkit as the primary install method

The goal of this plan is to clean up the repository, mark legacy content clearly, improve English quality, and make the documentation reflect the current recommended workflows.

Phase 0 — Spec and governance ✅

  • Create CONTRIBUTING.md with editing spec
  • Create drafts/ folder
  • Create old-probably-safe-to-delete/ folder
  • Create this IMPROVEMENT-PLAN.md

Phase 1 — Reorganise untracked files

Move untracked files into the appropriate folder without breaking any existing tracked wiki links.

Move to drafts/

File Reason
Ongoing-Maintenance.md Empty draft
Troubleshooting-docker.md Informal notes, useful in future
images-service-migration-to-1.0.md Technical notes without wiki format
agents.md Internal AI knowledge base, keep but not as a public page
2025-03-Madrid-Workshow-documentation-intro.md Workshop presentation draft

Move to old-probably-safe-to-delete/

File/Dir Reason
SBDI-pres.md / SBDI-pres.html External presentation, outdated
Presenting-the-La-Toolkit.html Binary export
Presenting-the-La-Toolkit.pdf Binary export
Presenting-the-La-Toolkit.pptx Binary export
Presenting-the-La-Toolkit/ (dir) Binary/export directory
conflu/ Confluence exports, historical reference only
bin/ Loose scripts, out of place
*.webm (all Kazam recordings, connectivity, etc.) Large binary files
*.mp4 (upgrading.mp4) Large binary file
creation.gif, creation.webm Binary media
monitor.webm, monitor-small.webm Binary media
pre-deploy.webm, deploy.webm Binary media
templates.webm, templates-small.webm Binary media
test.webm Binary media
signal-desktop-keyring.gpg System file, should never be here
Add-Search-Engines-to-Chrome.md2 Duplicate with wrong extension
image-2022-06-01_16:01:07.png Loose image, likely orphan
image-2022-06-01_16:23:30.png Loose image, likely orphan
Untracked img/ files Audit references before moving

Note: Presenting-the-La-Toolkit.md (the .md file) stays in root — it is tracked in git. Link to the la-toolkit GitHub repo directly in Quick Start, not to this presentation.

Status: ⬜ TODO

Phase 2 — English and typo corrections (tracked files only)

Safety rule: Body text only. Never touch anchor names, wiki links, code blocks, or example URLs.

Process:

  1. Audit script lists candidates per file
  2. Manual review of each suggestion
  3. One commit per file

Known issues already identified:

  • Github-good-pratices.md → body text: "pratices" → "practices" (filename stays)
  • LA-Quick-Start-Guide.md → various minor issues to audit
  • General: inconsistent capitalisation in headings across multiple files

Status: ⬜ TODO

Phase 3 — Mark legacy / deprecated content

Add blockquote legacy notices at the top of deprecated sections. Do not remove content.

Template:

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

Files needing legacy notices:

File What to mark
Jenkins-For-Biocache-Store-And-Other-LA-Tasks.md Entire page — biocache-store era
Data-ingestion.md biocache-store sections
Data-management.md biocache-store sections
Sample-And-Index.md Verify: biocache-store or pipelines?
Infrastructure-Requirements.md biocache-store aka biocache-cli mention
LA-Quick-Start-Guide.md Remove ala-demo recommendation; replace with la-toolkit
building-from-source.md Audit for outdated build instructions

Status: ⬜ TODO

Phase 4 — la-toolkit prominence in Quick Start

Current state: LA-Quick-Start-Guide.md Install section mentions:

  1. ala-install ansible (as primary)
  2. generator-living-atlas (as helper)
  3. ala-demo playbook (obsolete — to be removed)

Target state:

  1. la-toolkit — recommended primary method, linked to https://github.com/living-atlases/la-toolkit
  2. ala-install + generator-living-atlas — described as the underlying mechanism la-toolkit automates (for advanced/manual use)
  3. ala-demo — removed from recommendations

Key constraint: Do not change the filename or any anchor URLs. Edit body text only.

Status: ⬜ TODO

Phase 5 — KB Ollama integration (future / advanced)

Once the Ollama KB is generated from all ALA repos via la-toolkit:

  • Audit version numbers mentioned in docs vs actual current versions in repos
  • Identify pages describing changed flows (e.g. CAS → OIDC migration)
  • Identify dead links (404s to GitHub files that moved or were deleted)
  • Propose targeted updates with evidence from source code

Status: ⬜ FUTURE

Files to audit for dead links / 404s

  • Any github.com/AtlasOfLivingAustralia/biocache-store/blob/... links — repo may have changed
  • https://tinyurl.com/la-bootstrap-sessions — external URL, verify alive
  • https://generator.l-a.site/ — verify alive
  • https://crowdin.com/project/ala-i18n/ — verify alive

Out of scope (explicit)

  • No new content pages unless filling a clear 404 or gap
  • No renaming of tracked files (breaks URLs)
  • No removal of existing content (deprecate, don't delete)
  • No binary files added to wiki root