Principles

Principles of a good wiki

• Organized - only contains the information you need, and the information you need is easy to find.
• Transparent - anyone can edit it from their first day on the job, and can see documents made by their predecessors
• Actionable - documents are not just meant to be read, they’re meant to influence decisions and improve the quality of tasks and projects.
• Engaging - wiki docs are far more than words. They are well-formatted, and include images, video, code embeds, and links to related content. They are pleasant to read.

What belongs in a wiki?

• Document all processes with 3+ steps
• Document anything you’ve repeated 3+ times
• Transfer any Google Doc you’ve referenced 3+ times

Document types

Our wiki structure is based on the Diátaxis framework. Specifically, because our wiki is geared towards docs with a clear application (not general knowledge acquisition), we use two of their four doc types: How-To Guides and Reference. These are stored in their respective folders.

Reference docs should be something that is consulted and act as a source-of-truth for a piece of information.

How-To guides should outline the steps of a process. It is action-oriented: focused on a single task and how to acheive it. Digressions or explanations should be extracted into reference documents.

Examples

Things that belong in our wiki:

• Synthesized notes, such as a working agreement (reference)
• Static resources, like onboarding docs and code review guides (reference)
• Solidified outcomes that came from decision docs (reference)
• Engineering notes on processes, like “how to set up a demo environment” (guide)
• Technical documentation on specific tools we use (guide)

Things that do not belong in our wiki:

• Meeting notes, agendas, or transcripts
• Real time collaboration like note-taking or comments
• Working documents