How to build a wiki for your engineering team
Engineers need a certain set of tools and processes to do their work. A custom wiki built in Notion lets you centralize all your eng team’s most important information.
- In this piece, you'll learn
- Why a wiki is critical for engineering teams
- Setting up your engineering wiki
- 1. Make a page
- 2. Make a subpage
- 3. Structure your pages
- 4. Many types of content for engineering docs
- Got it? Good. Now take it a step further.
- See it in action
- Next steps
With the right tool, organizing all your team's important information in one place is pretty simple.
But from where you sit now, it probably feels daunting. Information may be scattered. It may be out of date. It may feel like an overpacked suitcase, where you have to pull out everything just to find the right pair of socks.
Trust us. Investing time in building a single, central engineering wiki will pay longterm dividends. Because a bad organizational system snowballs, and it can lead to inefficient work — time wasted looking for the right thing, outdated info, duplicative projects, incorrect processes.
Here, we'll walk you through building your own engineering wiki using Notion (you might also call it a knowledge base), and how it can unlock a better workflow for your team.
In this piece, you'll learn
In this piece, you'll learn
- 1
How to create a wiki for your engineering team, step-by-step
- 2
How to customize it to match your team's needs
- 3
How to use features and integrations that are useful for engineering specifically
Here's just one example of what your finished product could look like:
Why a wiki is critical for engineering teams
Ask yourself: where does all your team's information live? If the answer includes multiple destinations, your team probably lacks a central source of truth for documents that are essential to working effectively.
You deserve one reliable resource for:
Code style guidelines, your triage rotation, and infrastructure information — all up to date and easily accessible by everyone on your team.
Onboarding resources for new engineers to help them get spun up and productive fast.
Pages specific to the various projects going on inside your engineering team so everyone stays in the know about who's working on what.
No wiki means no hub for this information, which could have downstream effects. Information gets siloed so no one has a complete picture of what's going on. More meetings and conversations get scheduled because that information isn't findable. Work gets inaccurate and inconsistent because an engineer has been using an outdated style guide.
An organized and accessible wiki helps alleviate these problems. No more sifting through graveyards of documents all called the same thing (which are probably stale and outdated, anyway).
Everyone on your team knows where to find what they need, so your team can focus on what's important.
Setting up your engineering wiki
Let's start with a few basics and work our way up from there.
1. Make a page
This is the starting point for just about everything you do in Notion. A page can contain anything — text, lists, videos, images, databases and more. Your wiki is a page you'll add other pages to.
To create a page, just hit the +
sign next to WORKSPACE
in your sidebar. If you're already inside a page, simply hit /
and type page
then press enter
. Every time you hit /
, you'll see your full menu of content options — we call this a "slash command."
You can also start with a template
2. Make a subpage
Here's the crux of making a wiki — you can have many pages inside of one page.
For example, inside your main Engineering page, you can have separate pages for your code repository, team meeting notes, testing guidelines and more. Each of these pages becomes a resource for your team and can live side-by-side.
To make one, type
/page
and pressenter
. Your new page will pop up, where you can give it a title and add any content. Use the back button to return to your wiki.To make many pages at once, list all the page names you want as text. Now select them all, click the
⋮⋮
icon that appears on hover, clickTurn Into
and selectPage
.
This way, all the parts of your engineering organization live in one place. Your team doesn't have to go on a scavenger hunt anytime they need something — they know to start at your wiki.
You now have the bones of a wiki. Time to organize it.
Add personality to your pages with emojis and cover art
3. Structure your pages
Let's organize your wiki for ultimate usability.
You can start with headers. Using /
again, select from H1
(the largest), H2
or H3
(the smallest) headers. Now you can use the drag-and-drop feature to organize the pages in your workspace.
First, use drag-and-drop to create columns. Grab the
⋮⋮
icon next to your header, and drag it all the way to the far right to create another column. The blue guides will help you.To add divider lines under your headers for a polished look, simply type three hyphens in a row.
Now, again using
⋮⋮
, grab any pages and drag them into the sections where they belong.
A category like "Infrastructure" might include "AWS" and "Redis" pages. All engineering teams are different, and Notion allows you to customize your wiki based on your team's needs.
Everything is accessible within a click or two. So forget about hunting for documents. Save your team valuable time by creating a clearly-structured wiki that provides signposts to all the information people need. Notion then becomes the starting point for your team's work.
4. Many types of content for engineering docs
The tools an engineer needs to do their job are different than other teams. Notion meets those needs so your team can stop shoehorning information into software that isn't flexible.
Within pages, you can embed different types of content to display your information. Hit /
to see some of the things you can create (among many others):
Code blocks in any language
A gist from Github
Diagrams
Figma files
Math equations in LaTeX
You can either select these options from the menu that pops up or start typing their name to bring them up faster and press enter
to add them. For example, /github
and /math
.
We've found that code blocks are especially helpful for engineering teams to share information vital to process and consistency. To add one, type /code
and press enter
.
Click the dropdown at the bottom right of the box that appears to select which language you want to use. Type or paste in any code you want to share with your team, whether that's a command to run for deployment, or commonly used commands.
Notion's flexibility allows many kinds of information to exist in one place — so for a project you're working on, a singular page can have everything you need to take it from idea to launch. No more bouncing between tools and tabs. Stop context switching and get more done.
Watch our 3-minute video that teaches you everything you need to know about code blocks
Got it? Good. Now take it a step further.
You can nest infinite pages in your wiki. And once it's all set up, you can access all its pages right from the sidebar.
Let's say that, within your engineering wiki, there's a page for "Teams." Within the "Teams" page are individual pages for the sub-teams that are part of your engineering org: iOS, Android, Web, Mac, Windows, etc.
This structure ensures every document has its place so you don't have a bunch of uncategorized mystery documents floating around without homes. This also makes it easy for teams to access all the documents nested inside of these pages.
That can happen right from the sidebar with just a couple clicks.
See it in action
Visual learner? We created a 7-minute video showing how to build a basic wiki.
Next steps
A well-built wiki can act as the hub for all the spokes of your engineering team.
It connects everyone. It moves projects forward. It unlocks better workflows. And with Notion, you can customize it to match how your team works.
Setting up an engineering wiki is an investment in your team and their work. We hope this helps you on the way.
Something we didn't cover?