Step-by-Step: Setting Up Source-Linked Docs for a New Repo

You cloned the repo. The README says "see wiki." The wiki says "ask in Slack." Slack says "check Linear." Welcome to the documentation scavenger hunt.

What this article solves: A sane first-week setup for source-linked docs on a new repo—without connecting nine tools on day one because a blog told you to.

Who this is for: Tech leads, founding engineers, and platform folks standing up ScopeDocs on a greenfield or freshly split service.

Before you connect anything

Spend ten minutes answering two questions:

1. Where will truth change? (Almost always GitHub for code.)
2. Where do arguments happen? (Usually Slack, sometimes a Fathom call nobody wrote up.)

Everything else is optional until someone on the team asks for it.

Step 1: Make the repo legible in GitHub

Source-linked docs are only as good as the artifacts you leave behind.

• Create the repo with a minimal README (what it is, how to run it, who owns it)
• Use a PR template with Why, What changed, and How to verify
• Agree on one channel (e.g. #team-payments) for design discussion—not seventeen side DMs

If your PR descriptions are empty, no integration will save you. You are just automating silence.

Step 2: Connect GitHub first

This is non-negotiable.

• Sign in to ScopeDocs → Integrations → GitHub
• Authorize read access and select the new repository
• Open Documentation settings and enable generation from PRs and reviews

Smoke test: Open a small PR (fix a typo, add a comment). After merge, confirm a doc exists with a link back to that PR. If the link works, your foundation is real.

Step 3: Add Slack (where decisions leak)

• Connect Slack and limit scope to engineering channels (skip #social unless you enjoy chaos)
• When a decision happens in thread, react with a bookmark or drop the thread link in the PR—ScopeDocs can pull that context into the doc

Pro tip: The phrase "we'll document it later" is a lie. Link the thread now; future you is tired.

Step 4: Add Linear or Jira—not both by default

Pick the tracker your team actually closes work in.

Linear teams:

• Connect Linear and map the project to this repo
• Reference ticket IDs in PR titles (PAY-412: retry webhook)

Jira teams:

• Connect Jira the same way—epics and incident tickets become first-class sources

Do not connect both unless your org genuinely uses both for the same work. You will duplicate context and blame the tool.

Step 5: Generate the first doc from a real PR

• Ship a meaningful change (feature flag, new endpoint, schema tweak)
• Write a human PR description (future readers will thank you)
• Let ScopeDocs generate architecture or feature docs from that PR
• Edit for tone—generated ≠ finished, but it should not sound like a robot ate a textbook

Step 6: Add Supabase when the database is part of the story

If this service owns tables, migrations, or RLS policies:

• Connect Supabase so schema and live data can ground answers
• Regenerate or refresh docs after your first migration merge

Skip this step for a static marketing site. Seriously.

Step 7: Add Notion, Confluence, or Google Drive when "official" docs live there

Goal: one searchable trail from wiki page → PR → ticket, not two wikis fighting.

Step 8: Add Fathom and Datadog when the audience shows up

• Fathom — PM and staff eng decisions happen on calls; summaries should be searchable next to the code that implemented them.
• Datadog — on-call asks "which monitor fired?" more often than "what is a pod?"

Add these when someone says "I can't find what we decided on that call" or "the runbook doesn't match our dashboards." Not before.

Step 9: Establish a boring maintenance habit

• Weekly: one engineer skims new docs for the repo (five minutes)
• On merge: PR author confirms the generated doc isn't nonsense
• On incident: link the fix PR to the incident ticket so the next postmortem writes itself

Rollout checklist (copy/paste)

• GitHub connected + PR-linked doc verified
• Slack channels scoped
• Linear or Jira mapped
• First doc generated from a real merge
• Supabase (if applicable)
• Notion / Confluence / Drive (if applicable)
• Fathom / Datadog (when asked for)
• Weekly five-minute doc skim on the calendar

What good looks like after week one

A new hire searches "webhook retries" and gets: what the service does, which PR introduced the retry policy, which Linear ticket scoped it, and—if you wired Supabase—which table stores idempotency keys. No wiki archaeology.

For a fuller picture of when to add each integration, read Engineering documentation integrations: what to connect first.

Connect your stack · See features