How to set up an engineering wiki in Notion (structure, databases and templates)
A copy-paste page structure for an engineering wiki in Notion, plus the databases, properties, templates, permissions and GitHub links that keep it useful.
The KnowWhyy team · · 9 min read
Most engineering wikis in Notion start the same way. Someone creates a page called "Engineering", a few people add sub-pages, and six months later there are three pages called "Onboarding", a runbook nobody trusts and a search bar full of near-duplicates. Notion isn't the problem. A blank page with no structure is.
This guide gives you a page structure you can copy, the four databases worth setting up on day one, the properties and templates that make them consistent, sensible permissions, how to connect GitHub, and a few habits that keep the whole thing from going stale.
Start with a wiki page, not a loose tree
Notion has a built-in wiki type. You can turn any standalone page into a wiki from the ••• menu, then More and Turn into wiki. A wiki comes with three views: Home, All pages (a database view of everything in the wiki) and Pages I own. Every page in it gets an owner, by default whoever created it.
The owner answers the question every reader has: who do I ask if this is wrong? It also powers verification, covered below.
Engineering (wiki home)
├── Start here
│ ├── How we work (one page: rituals, on-call, review rules)
│ ├── Who owns what (link to Services database, filtered by team)
│ └── Glossary
├── Onboarding
│ └── Onboarding checklists (database)
├── Systems
│ ├── Architecture overview (one diagram, one page)
│ ├── Services (database)
│ └── Environments and access (how to get to staging, prod, logs)
├── Decisions
│ └── Decision log (database)
├── Operations
│ ├── Runbooks (database)
│ ├── Incident postmortems (database or linked from Runbooks)
│ └── On-call handbook
├── How-to guides
│ ├── Local development setup
│ ├── Releasing
│ └── Adding a new service
└── Archive
A few rules make this structure hold:
One page per topic. If two pages cover the same thing, merge them and leave a link where the old one was.
Databases for anything you'll have more than ten of. Services, decisions, runbooks and onboarding checklists all grow. A database gives you filters, owners and templates. A pile of sub-pages gives you none of that.
An Archive section from day one. People delete old pages more readily when there's a clear place to move them.
Home page as a map, not a document. The wiki Home view lets you add headings and drag pages under them. Use it as a table of contents with one-line descriptions.
The four databases worth having
Decision log
The place for "why did we choose this?" Each entry is one decision, written when it's made. If your team already writes ADRs in the repo, keep them there and use this database for product, process and tooling decisions that don't belong next to code. See architecture decision records that stick for a template.
Property
Type
Why
Status
Select: Proposed, Accepted, Superseded, Rejected
Readers need to know if it still applies
Date decided
Date
Lets you line it up with the code that followed
Area
Multi-select
Filter by billing, auth, infra and so on
Deciders
Person
Who to ask
Superseded by
Relation (to itself)
Points old decisions at the new one
Links
URL or text
PR, issue, Slack thread
Services
One row per service, job or significant component. This becomes your service catalog and your "who owns what" page.
Property
Type
Why
Owner team
Select
First stop when something breaks
Tech lead
Person
A named human, not just a team
Repository
URL
One click to the code
Tier
Select: Critical, Important, Internal
Sets on-call expectations
Runbooks
Relation to Runbooks
The fix is one click away
Decisions
Relation to Decision log
The "why" is one click away
Dashboards
URL
Where to look first
Runbooks
Step-by-step instructions for a specific alert or task: "Queue depth above 10k", "Rotate the database password". Relate each runbook to the services it covers. The runbook template post has a full structure.
Property
Type
Why
Service
Relation to Services
Find the runbook from the service page
Trigger
Text
The alert name or situation, so search finds it
Last tested
Date
A runbook nobody has run is a guess
Severity
Select
Matches your incident levels
Onboarding checklists
One page per new hire, created from a template. It gives every new engineer the same path and gives you a record of what they found confusing. Pair it with the habits in speed up developer onboarding.
Property
Type
Why
New hire
Person
Owner of the checklist
Buddy
Person
Who answers the small questions
Start date
Date
Sort and track progress
Team
Select
Picks the right team-specific steps
Status
Status
Not started, In progress, Done
Templates that make every page look the same
Consistency is what makes a wiki skimmable. Notion's database templates let you define a page structure once and reuse it from the dropdown next to New. You open + New template, set default property values and write the page body. Templates only exist in the database where you create them, so build one per database.
A decision template:
## Context
What problem are we solving? What constraints matter (cost, deadline, team skills)?
## Decision
One or two sentences. Start with "We will..."
## Options considered
- Option A: why not
- Option B: why not
## Consequences
What gets easier, what gets harder, what we now have to maintain.
## Revisit if
The signal that should make us reopen this (traffic, cost, a vendor change).
## Links
PR, issue, Slack thread, related decisions.
A runbook template:
## When to use this
Alert name or symptom, exactly as it appears in the pager.
## Check first
1. Dashboard link
2. The one query or command that confirms the problem
## Fix
1. Step, with the exact command
2. Step, with the expected output
## If that doesn't work
Who to escalate to, and what to tell them.
## Last tested
Date and person. Update every time someone runs it.
One caution from Notion's docs: don't fill in relation properties inside a template unless you want every new page to link to the same record. Leave Service or Superseded by empty in the template and fill it on each page.
Permissions: open by default, locked where it counts
Engineering docs work best when everyone can read them. Notion's permission levels are Full access, Can edit, Can edit content, Can comment and Can view, plus Can create on Business and Enterprise plans.
A setup that works for most teams:
Area
Engineering
Rest of company
Why
Wiki pages and how-tos
Can edit
Can view
Anyone can read, engineers keep it current
Database structure (properties, views)
Can edit content for most, Full access for a few
Can view
Stops accidental property changes
Runbooks
Can edit
Can view or no access
Some runbooks reference internal systems
Security and access docs
Restricted group
No access
Keep secrets out of Notion entirely; link to your vault
Can edit content is the useful one here. It lets people add and edit rows in a database without changing its properties, views or filters. Give it to most of the team and keep Full access for the two or three people who maintain the structure.
Linking Notion to GitHub
Engineering docs get much more useful when they point at the code and the PRs behind them. Notion has three GitHub features. Check your plan first, because Notion's help pages list two of them as Business-plan features.
Link previews. Paste a GitHub link into Notion and choose Paste as: Preview for a card, or Paste as: Mention for an inline chip. The link preview docs say the preview updates as the linked content changes. The first time, you connect your GitHub account. One thing to know before you do this on a company-wide page: once you've authenticated, anyone who can view the Notion page can see the content you pasted as a preview. Don't preview a private repo's PR on a page shared outside the team.
Database sync (Business plan). Notion's newer GitHub database sync imports pull requests, issues or both from the repositories you pick, into a database that Notion keeps up to date in the background. Synced properties are read-only. You edit in GitHub. You can add your own Notion properties alongside them, for example a relation from a PR to a decision. Things to know:
It's only available on the Business plan, according to the help page.
You choose a history window: all history, or the last 30, 90 or 365 days, based on each record's last update. Records that fall outside the window are removed, including any values in your own Notion properties. Pick all history if you plan to annotate PRs.
The synced database starts private. If you share it, viewers don't need access to the source repository, so review permissions before sharing data from private repos.
It replaces the legacy GitHub sync. Notion says legacy synced databases stopped updating after October 30, 2026, so if your workspace used the old "Paste as database" sync, set up the new one.
GitHub Pull Requests property (Business and Enterprise). A connected property you add to a task database. It adds a Unique ID to each task. You either put that ID in the pull request or paste the PR URL into the property. This suits teams that plan work in Notion.
If you're not on Business, the habit that matters most is free: put the PR link in the decision or runbook page, and put the Notion link in the PR description. Two-way links are what let someone get from code to context.
Keeping it from going stale
A wiki decays from the day you create it. Three things slow it down.
Owners and verification. In a wiki, page owners can mark a page as verified until a date or indefinitely. Verified pages show a blue check in search and @-mentions. When verification expires, the owner gets a Notion inbox notification and an email. Set runbooks and onboarding pages to expire every 90 days. Leave decisions verified indefinitely, since a decision record describes a point in time. Verifying pages outside a wiki, or adding a Verification property to a regular database, needs a Business or Enterprise plan. Admins can see every verified page under Settings, then Verified pages.
A review ritual. Add a Pages I own check to an existing meeting once a month. Five minutes per person is enough to re-verify, archive or fix.
Docs near the code where it makes sense. Setup steps, API references and ADRs often live better in the repository, where a PR can update them alongside the code. Notion is better for cross-team explanations, onboarding and decisions that aren't tied to one repo. The guide to keeping internal docs up to date covers this split, and Confluence vs Notion for engineering docs compares how each tool handles page history and search.
Where KnowWhyy fits
Even a well-kept wiki holds only part of the story. The rest is in PR discussions and Slack threads. KnowWhyy connects the Notion pages, GitHub repositories and Slack channels you choose, and answers questions in its web app with a link to every source it used, for example "why did we split the billing service?" Answers only use sources the person asking is allowed to see, and if nothing indexed covers the question, it says so. It isn't a wiki and doesn't replace one. It makes the wiki and everything around it searchable by question. See AI search for your Notion knowledge base, or start free with up to 2 members.
The short version
Turn your engineering page into a Notion wiki so every page has an owner, and keep the top-level structure to a handful of sections.
Use databases for decisions, services, runbooks and onboarding, with relations between them, and one template per database.
Give most engineers Can edit content on databases and keep Full access for a few maintainers. Keep secrets out of Notion.
Use GitHub link previews to show PRs and issues inside pages. Database sync and the PR property need a Business plan, and the legacy sync stopped updating after October 30, 2026.
Use page verification with expiry dates and a monthly owner check, and keep code-adjacent docs in the repo.