Skip to content

Documentation conventions (EDOS workspace)

Audience: Agent + operator

This file defines how documentation in this tree is written so humans and coding agents can rely on consistent structure, terminology, and uncertainty handling.

Workspace model

  • Workspace (edos): A single directory that holds several independent projects side by side. It is not a monorepo: there is no shared root package, workspace-wide build, or enforced single version line across projects.
  • Project / app: One top-level folder under the workspace root (for example elite-dangerous-surface-map, inter-frame-messenger). Each project has its own repository history, tooling, and release lifecycle unless explicitly stated otherwise.
  • Documentation repo (future): Documentation may live in a separate repository that mirrors or references this layout. Paths in docs are written relative to the docs root (docs/) or the workspace root when pointing at code; always state which.

Terminology

Term Meaning
Journal Elite Dangerous player log files (line-delimited JSON events), as consumed by local/remote readers in this ecosystem.
IPC (here) Mechanisms that connect host processes (native apps, shells) with embedded UIs (e.g. WebView, iframe), including postMessage and shared libraries dedicated to that. Not the same as OS-level IPC unless explicitly stated.
Host The application that owns the window or embeds web content (e.g. desktop shell loading a URL or local HTML).
Embedded UI / web app HTML/JS (or framework) running inside a WebView or browser surface, receiving or sending messages to the host.
Community tooling Third-party Elite Dangerous tools that may embed or interoperate with these projects; compatibility targets (e.g. WebView2) are documented in architecture notes, not assumed here.
Community HTTP APIs Public HTTP services maintained by players (e.g. SPANSH, EDSM). Often no DDoS or rate-limit infrastructure; apps must use the API cache server (or equivalent) instead of calling those URLs directly — see ARCHITECTURE.md.

Use project when referring to a repo/folder; use app when emphasizing the user-facing deliverable (often the same boundary).

File naming and layout

  • UPPERCASE.md for stable, top-level doc types: SCOPE.md, ARCHITECTURE.md, REPOS.md, AGENTS.md, etc.
  • docs/apps/PROJECT_SLUG.md for per-project capsules (Phase 3), where PROJECT_SLUG matches the folder name under the workspace root (e.g. elite-dangerous-surface-map.md).
  • TODO.md (optional): consolidated open documentation gaps; avoid scattering permanent TODO sections in multiple files without an index.
  • Prefer relative links between docs: [Architecture](./ARCHITECTURE.md).
  • When linking to code, use a path from the workspace root in backticks: `elite-dangerous-surface-map/ui/src/...` so it is searchable. If the doc repo is separate, state that code paths are relative to the code workspace checkout.
  • For external references (MDN, Frontier forums, etc.), use the full URL in markdown link form.

Diagrams

  • Use Mermaid in markdown where diagrams help (sequence, flow, simple graphs). Keep diagrams small; split into multiple figures rather than one unreadable chart.
  • Prefer one canonical system diagram in ARCHITECTURE.md (or equivalent); repeat only when a local diagram clarifies a subsection.

Uncertainty and facts

  • Documentation must not invent APIs, message shapes, or file paths. If behavior is not verified from code or existing authoritative notes, mark it explicitly:

TODO: Verify — short hint where to look, e.g. TODO: Verify — message envelope in inter-frame-messenger (search postMessage).

  • When the source is known, prefer path:line (or a small line range) so agents can jump in the editor:

See elite-dangerous-local-journal-reader/.../foo.ts:42 for tail implementation.

  • Do not leave vague TODOs (“check later”) without a next step (file, symbol, or grep hint).

Style for agent-oriented pages

  • Imperative checklists for procedures (“Before changing IPC, read …”).
  • Tables for contracts (message fields, env vars, CLI flags).
  • Short sections with clear ## headings; avoid walls of prose.
  • Scannable over literary: agents and humans both skim for anchors.

Relationship to original-concept.md

  • original-concept.md captures early postMessage / WebView considerations. New architecture docs may supersede or narrow that content; when they diverge, the newer doc should state that and point to the code that is authoritative.

Changelog

  • Doc-only changes are recorded in CHANGELOG.md. When the documentation moves to its own repo, keep that file at the docs root there.

Entry point