Contributing to the Metashape Expert Manual¶

This project is built incrementally by a mix of human authors and AI agents under human review. Before contributing, read STRATEGY.md — particularly §9 (Execution Model and Quality Controls).

Ground rules¶

1. No agent merges. An agent may draft, critique, lint, suggest, or refactor. An agent may not approve a PR or set an article's status to verified. A human maintainer who has reproduced the procedure on a real Metashape install must do that.
2. Every published article is either author-validated or carries an unverified badge. No exceptions.
3. Every article cites at least one official-manual reference and at least one forum reference, or carries an explicit "original synthesis" flag.
4. Every article pins a Metashape version, declares a confidence level, and lives in exactly one Diátaxis mode (how-to, explanation, or reference).

Workflow¶

The canonical authoring order, validated by the alignment-quality pilot (see retrospectives/pilot.md):

1. Pick (or be assigned) an article from the active wave doc in waves/wave-NN-*.md.
2. Insight cards first. Curate the 3–7 forum threads that will ground the article. For each, write an insight card in insights/ before drafting prose. The cards are the article's source-of-truth citations and prevent the drafting step from drifting into speculation.
3. Draft the article using the template in STRATEGY.md §3.2.
4. Run Tier 1 automated verification (per STRATEGY.md §9.11) before requesting review. Use the helpers:

# Build first; some checks need the rendered HTML.
./.venv/bin/mkdocs build --clean --strict

# Tier 1 sweep — all five must report 0 issues:
./.venv/bin/python scripts/verify_article.py \
    docs/workflow/<stage>/<your-article>.md
./.venv/bin/python scripts/verify_demo_code.py \
    docs/workflow/<stage>/<your-article>.md
./.venv/bin/python scripts/verify_quotes.py \
    docs/workflow/<stage>/<your-article>.md
./.venv/bin/python scripts/audit_personal_references.py \
    docs/workflow/<stage>/<your-article>.md
node scripts/verify_mermaid_rendered.js site/

The five checks cover:

- `verify_article.py` — Python API introspection + PDF
  menu-label lookup + terminology-shift sweep.
- `verify_demo_code.py` — every `Metashape.X.Y` reference in
  Python code blocks resolves on the local install.
- `verify_quotes.py` — every blockquote near a forum
  permalink matches the cached source HTML verbatim.
- `audit_personal_references.py` — personal names only in
  attribution lines / References / link labels (per the
  personal-name rule in [`STYLE.md`](https://github.com/PhotogrammetryCommunity/metashape-expert-manual/blob/main/STYLE.md)).
- `verify_mermaid_rendered.js` — Mermaid diagrams parse
  cleanly in the *built* HTML (catches the
  mkdocs-mermaid2 HTML-stripping bug class that the
  markdown-source mermaid-parse cannot detect).

The output is markdown formatted; paste the relevant findings (and any corrections you applied as a result) into the PR description's Automated verification log section. 5. Run the per-article self-review checklist below. 6. Open a PR. CI will run lint, link check, and the template-compliance check. A critic agent will post an automated review. 7. Address review comments. A human maintainer validates the procedure on a real Metashape install before merge. 8. After merge, update the wave doc and JOURNAL.md.

Per-article self-review checklist¶

Run this before submitting any draft for review.

• Article uses the §3.2 template (or the explanation/reference simpler templates).
• Article belongs to exactly one Diátaxis mode.
• If a how-to: Context section is one short paragraph (≤ 5 sentences) per STYLE.md. No drift into explanation mode.
• Tier 1 automated verification has been run per STRATEGY.md §9.11. The PR description carries the Automated verification log.
• edition: field is set (Standard or Pro); edition rule in STYLE.md followed.
• At least one official-manual reference is present.
• At least one forum reference is present (or "original synthesis" flag is set with justification).
• Every forum citation includes date AND version-at-time per STYLE.md (D11). Use docs/reference/version-timeline.md to look up the version.
• Any feature this article relies on heavily is linked to its docs/reference/features/<slug>.md page (D12), and that feature page has been updated to mention this article.
• Applies to: field names a specific Metashape version range.
• Confidence: field is set (high / medium / low) with one sentence of justification.
• Status: field is set (verified / unverified / deprecated).
• No claim is made that isn't supported by an in-text reference, reproducible procedure, or stated reasoning.
• No license-circumventing or unsupported-export trick is documented (per STYLE.md).
• GUI steps name menu paths exactly as they appear in the current Metashape version.
• Python snippet (if any) imports Metashape and would run as shown — no pseudocode silently mixed in.
• All images have alt-text and a captioned source dataset.
• If the article needs a dataset to illustrate or validate, an Agisoft sample dataset has been considered first (see docs/reference/sample-data.md); a contributor-private dataset is used only when no sample fits, and the article says so.
• Heading hierarchy is unbroken (no jump from ## to ####).
• Any claim the author could not personally validate carries an inline UV-NNN marker linking to docs/about/unverified.md, and the corresponding tracker entry is filled in (per STYLE.md § "Marking unverified claims inline").

Per-wave relevance check (after each wave)¶

After completing a wave (or any batch of ≥ 3 new articles), run this review pass before declaring the wave complete. It guards against publishing content that substantively duplicates the official manual, the freshdesk tutorials, or existing articles in the corpus.

For each new article, fill in a one-row entry:

| article | manual coverage of same topic | this article's value-add | tier |

Tiers:

• A: Manual / freshdesk does not cover the topic at all (forum- only API surface, undocumented tweak, forum-attested gotcha).
• B: Manual / freshdesk covers the topic at a different depth or scope; the article either goes operationally deeper, addresses a forum-attested gotcha, or surfaces a use-case not in the docs. The article must include an explicit scope statement (in the opening section or Confidence callout) naming what the manual covers and where the article picks up.
• C: Substantively duplicates manual or existing article. C-tier articles must be rewritten or cut before the wave is declared complete.

The review report goes in retrospectives/wave-NN-relevance-review.md (template: retrospectives/wave-15-18-relevance-review.md). The wave's JOURNAL entry must reference the review.

Heuristics for the reviewer:

• The novelty-signal score from scripts/manual_cross_check.py is a weak prior, not a verdict. Low novelty (< +10) warrants a closer read; it does NOT automatically mean the article is redundant.
• Articles that explicitly point to where the manual covers the basics tend to read more rigorously than articles that imply differentiation. Encourage Tier B articles to add an explicit scope statement.
• "Relevant to whom?" Each article should solve a concrete reader pain point — preferably one that surfaced in the source forum thread. Articles whose only value is "the API exists" without a use-case framing get pushed to Tier C.

Nav ordering check (also per-wave)¶

After every wave that adds articles, also verify the affected sections in mkdocs.yml are still ordered by importance per STRATEGY.md §3.1.1, not chronologically. New articles slot in at their importance tier:

1. Foundational concepts (used by many other articles).
2. Core operations (daily-use APIs / workflows).
3. Recipes (focused how-tos).
4. Specialised (less-common scenarios).
5. Reference (undocumented tweaks, deep API surfaces) — last.

Articles in a deliberate Series stay in their series order even if that conflicts with the importance principle (the sequence itself is the signal).

The check at the section level: scan the section's TOC and ask "if a reader scrolled this list looking for what to read first, would they find the most-foundational article at the top?" If not, reorder.

The check at the cross-section level: section ordering goes most general → less general — see STRATEGY.md §3.1.1 for the canonical order.

Reordering is a mkdocs.yml-only change; article content does not move. Verify with mkdocs build --strict to catch typos in the nav entries.

Style¶

• Primary: Google Developer Documentation Style Guide.
• Secondary: Microsoft Writing Style Guide.
• Project-specific overrides: STYLE.md.
• US English. Active voice. Second person ("you"). Sentence-case headings.

Working notes discipline¶

If your work spans multiple sessions:

• Read STATUS.md and the latest JOURNAL.md entry first.
• Update the active wave doc as you work.
• Append to JOURNAL.md at the end of every session. A session that produces no journal entry is treated as incomplete.
• Refresh STATUS.md if anything changed.

Reporting issues¶

• Factual errors in published articles → file an issue with the accuracy label. Treated as P1; triaged within 7 days.
• Broken links → file an issue with the link-rot label, or wait for the monthly CI sweep.
• Style or template issues → PR welcome.

Insight cards¶

Insight cards in insights/ are internal authoring notes, not published content. They have lower bars for prose quality but the same bars for citation and accuracy. See STRATEGY.md §4 Phase 2.