Skip to content

docs: collate and restructure import/export feature documentation #84

Description

@pskillen

Problem

Import and export documentation is split across docs/features/import/ (8 files) and docs/features/export/ (1 file), with overlapping hubs, stale progress logs, and multiple outstanding files from completed initiatives (#7, #38, #58). Contributors must jump between directories and guess which log is still authoritative.

Meanwhile the reference layer has matured: wire-format detail lives in docs/reference/opengd77/ with a generic format + radio profiles split (radios/baofeng-1701.md, room for more). Feature docs still duplicate column tables and mix adapter behaviour with reference material.

Before adding DM32 (#67), qDMR (#37), and more OpenGD77 radio profiles, we need a tidier import/export doc tree and a single "adding a new vendor" guide that collates process notes scattered across import README, export README, format-fidelity.md, AGENTS.md, and code comments.

Intended outcome

Documentation-only refactor (no behaviour changes unless broken links force tiny comment updates).

1. Collate progress / outstanding logs

Current files (import/):

File Initiative Status
genericise-import-progress.md #7 Complete
genericise-import-outstanding.md #7 All items checked
opengd77-progress.md #38 Complete (pending merge note — update)
opengd77-outstanding.md #38 Active debt (APRS/DTMF)
active-import-progress.md #58 Complete
active-import-outstanding.md #58 One optional fixture item

Actions:

  • Archive or delete completed progress logs (or fold a one-paragraph "history" into the hub README).
  • Single outstanding file: import-export-outstanding.md — merge remaining open items from all *-outstanding.md files; remove duplicates; drop completed checkboxes.
  • Do not carry forward empty "discovered during execution" sections.

2. Combine into docs/features/import-export/

Replace separate import/ and export/ folders with one feature area:

docs/features/import-export/
  README.md                 # unified hub (problem, status, architecture, merge modes, UI)
  outstanding.md            # single collated debt log
  adding-a-new-vendor.md    # contributor guide (see below)
  opengd77/
    README.md               # adapter behaviour only — points to docs/reference/opengd77/
    progress.md             # optional: keep one short execution log if still useful
  dm32/                     # placeholder README stub for #67 (optional)
  • Merge content from import/README.md + export/README.md into the new hub without losing merge-mode docs, test commands, or wire-format cross-links.
  • Delete empty docs/features/export/ after migration.

3. OpenGD77 vendor subtree

Move adapter-focused docs to docs/features/import-export/opengd77/:

  • opengd77.md → slim adapter behaviour doc (classification, detectKind, skip/error behaviour, merge interaction) — column tables stay in docs/reference/opengd77/.
  • Cross-link prominently:
  • Leave room for opengd77/radios/<radio>.md only if adapter behaviour genuinely differs per radio; default is one adapter + reference radio profiles.

4. adding-a-new-vendor.md (key deliverable)

Read existing docs and code; produce a checklist-style contributor guide covering:

Section Contents (pull from existing sources)
When to add New vendor format vs new radio profile on existing format (OpenGD77 example)
Reference docs Create docs/reference/<vendor>/ wire-format pages; ground truth sources; FK rules
Code layout src/lib/import/<vendor>/, src/lib/export/<vendor>/; register in registry.ts; vendorFormats.ts
Data model What must extend Codeplug vs vendorExtras; link data-model
Tests Per format-fidelity.md: parse unit tests, serialise unit tests, roundtrip.test.ts, merge/system tests, synthetic bundles under src/test/<vendor>/
UI ImportDropzone / ImportIntoActivePanel classification; Export page format switcher (#81 secondary nav)
Lossy fields Document header-only / skipped files; update outstanding.md
Docs to update Hub README, docs/features/README.md, AGENTS.md, docs/build/testing/README.md, component sidecars
Cross-format Internal model as hub; optional cross-export tests when two vendors ship
Manual verify Import folder → CRUD touch → export → re-import diff

Include a worked example outline pointing at OpenGD77 as the reference implementation.

5. Update inbound links

Fix references across the repo after moves:

  • AGENTS.md, docs/features/README.md, docs/build/testing/*.md
  • src/lib/import/opengd77/adapter.ts header comment
  • Component sidecars (ImportIntoActivePanel.md, etc.)
  • GitHub issue bodies — only if maintainer wants (optional; links may 404 until merged)

Affected

  • docs/features/import/ → remove after migration
  • docs/features/export/ → remove after migration
  • docs/features/import-export/ — new tree
  • docs/features/README.md — single Import/export row
  • .cursor/skills/feature-docs/SKILL.md — note combined folder pattern if convention changes (optional small update)

Notes / dependencies

Out of scope

  • Writing DM32 or qDMR adapter docs content (stubs/placeholders only).
  • Implementing new vendors.
  • Moving docs/reference/ under import-export/ — reference stays vendor-neutral and shared.

Manual verify

  1. No broken relative links from docs/features/import-export/README.md.
  2. adding-a-new-vendor.md links to format-fidelity, data-model, OpenGD77 reference, and registry code paths.
  3. outstanding.md contains only open debt (APRS/DTMF, optional real fixtures, export profile picker follow-ups).
  4. docs/features/README.md index updated.

Workflow note

Branch from origin/main, atomic conventional commits (outstanding collate → new tree + moves → adding-a-new-vendor → link sweep → delete old dirs), PR linking Closes #.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions