Audio to Markdown for GitHub: Meeting Decisions as Documentation
Most engineering decisions are made in calls and lost to memory. The dissents disappear. The reasoning evaporates. Six months later, no one remembers why the system is structured the way it is, and the engineer who made the call has long moved on. Transcribe the meeting, convert to GitHub-Flavored Markdown, commit as <code>docs/adr/</code>. Now the decision is part of the repo's permanent record.
ADRs derived from voice
Architecture Decision Records (ADRs) are the standard pattern for capturing why a system is built the way it is. The pattern usually fails at the writing step: engineers don't want to type up a meeting they just spent an hour in. Transcribing instead makes ADRs free: the decision was already discussed verbally, the transcript captures it verbatim, and the commit is one PR away.
Convert each decision meeting on Audio to Markdown, save as docs/adr/2026-01-15-event-system.md with a short preamble (Context, Decision, Consequences) prepended to the transcript. Commit. The PR review captures dissents that came up post-meeting; the merged file is the canonical record.
Where this lives in the repo
Common conventions: docs/adr/ for canonical decision records, docs/meetings/ for routine standups and status calls (less ceremony), docs/postmortems/ for incident review transcripts. All in GitHub-Flavored Markdown, all rendered nicely on GitHub's file viewer, all searchable via GitHub's code search.
Linking decisions to code
In the relevant code file, comment: // See docs/adr/2026-01-15-event-system.md for the decision context. GitHub renders the path as a clickable link in the file viewer. Future engineers reading the code land on the actual transcript with attribution and context. Pair with PDF to Markdown for GitHub for vendor specs and URL to Markdown for GitHub for reference articles.
Frequently asked questions
Is the converted Markdown GitHub-Flavored Markdown compatible?
Yes: the converter targets GFM. Headings render correctly, code fences with language hints get syntax highlighting, tables use pipe syntax, lists nest properly. Transcript section headings (## Pricing objections [00:14:22]) render as standard heading-2 blocks on GitHub's file viewer.
How do I structure an ADR derived from a meeting transcript?
Standard ADR template at the top: Status (Accepted / Superseded / Deprecated), Context (one-paragraph summary of what we were deciding and why now), Decision (the actual decision in one sentence). Then the full transcript below as the source-of-truth record. Future readers get the summary up top and the verbatim discussion below.
Where in the repo should transcripts live?
docs/adr/ for architecture decision records (canonical, long-lived). docs/meetings/ for routine status calls (lighter weight). docs/postmortems/ for incident reviews. All under docs/ keeps them out of source-code search by default while remaining first-class searchable content via GitHub's repo search.
Can I link from a code file to the meeting that decided it?
Yes; use a relative-path comment: // See docs/adr/2026-01-15-event-system.md for the decision context. GitHub renders the path as a clickable link on its file viewer. Cursor, VS Code, and most modern editors also follow the link inline. The trail from "weird-looking code" to "this is why" stays intact for years.
Should I commit raw transcripts or hand-edited summaries?
Both, in different files. docs/adr/2026-01-15-event-system.md as the polished decision record (ADR template + key excerpts). docs/meetings/2026-01-15-event-system-raw.md as the full transcript. The polished file is what most readers consume; the raw transcript is the unedited evidence anyone can audit.