Writing as a Default: How Shopify Keeps Technical Knowledge Flowing
When new engineers join a company, their first challenge is rarely the code itself—it's the context. Codebases are unfamiliar, setup instructions are vague or missing entirely, and the knowledge lives with people who may be in a different time zone. The cost is even higher in remote work, where asking questions means breaking focus for both parties.
Shopify's answer is a documentation culture that treats technical writing as a core engineering practice. The company's internal engineering blog posts about its own practices offer an interesting case study in making documentation productive at scale. The reasoning is simple: written knowledge is searchable, shareable, and can be accessed asynchronously—making it the natural fit for cross-time-zone teams.
The Problem With Untracked Knowledge
Technical context is communication fuel. When it's only in someone's head, every question requires a conversation, and answers reach only the people in that conversation. It's an inefficient system that compounds as teams scale. New hires ask the same questions, teams rebuild the same APIs, and knowledge disappears when people switch projects or leave the company.
Documentation suffers further because it's often scattered across platforms, written inconsistently, and deprioritized behind actual code. Shipping new features feels more productive than documenting existing processes, but that short-term efficiency creates long-term friction.
Shopify's take is that documentation isn't a chore but an operational asset. To make it sustainable, they standardize how it's written, keep sources of truth aligned, and, above all, lead by example. The most effective way to prompt engineers to write, they've observed, is to write themselves—whether that's pulling together a quick PR or contributing to the company's main internal wiki.
Where Internal Documentation Lives
Irrespective of effort, documentation only becomes valuable when it's in the right place. Shopify channels it into three primary tools, each serving a different purpose.
Markdown Microsites
Microsites, built with the Docusaurus templating engine, house technical content that lives close to the source code. Because the docs are tracked in the same repositories and go through the same peer-review process as code, they're easier to keep current. Writers can work from their IDE without switching contexts. Since the content is plain Markdown, migrating it to other platforms is straightforward; Shopify plans to fold these sites into its central internal platform to increase overall discoverability.
GitHub
For engineers, GitHub is the primary source for operational answers: bug status, ticket states, project roadmap. The issue tracker integrates with daily engineering workflow, and its search function makes it simple to explore those specific questions—or to locate examples of a given API and understand how certain code is implemented. README files accompany each project and capture onboarding essentials such as environment setup and testing procedures.
The Vault
Shopify's internal wiki, called the Vault, is the company's main mechanism for what they call "Default to open." First created in 2012, when the company had just over 150 employees, it has adapted as scale forced an upgrade in content management. The Vault uses Git and Markdown, so page editing is flexible, and version history is trackable. It's the single place that covers contextual company information, from departmental updates to technical deep dives.
What Solid Docs Actually Accelerate
A good documentation culture gives a measurable productivity boost—while minimizing how much time is wasted hunting for help. Clearly, when answers are a few clicks away, there's no need for a conversation just to scrape a bit of context.
That speed compounds inside teams. Lessons gleaned from past project failures don't need to be re-learned through trial and error. Supported engineers can quickly get up to speed on internal packages without needing an email chain; they can see how dependencies are mocked and what a successful implementation looks like.
Documentation directly improves the onboarding experience. New joiners or people moving to new teams don't have to rely on asking questions as their only route to knowledge, and can read through the material at their own pace. A consistent onboarding path is about more than efficiency—it also creates a shared baseline experience and reinforces a sense of belonging. New team members can fill documentation gaps, giving them a low-stakes early entry point into a project.
Written docs are also a subtle tool for inclusion. They level the playing field for engineers who aren't native English speakers, and they make contribution and review accessible outside specific hours or time zones. Documentation becomes a shared team responsibility rather than someone's individual role, further supporting collaboration. When an engineers' first look at a new package or API is high-quality documentation, they'll feel more comfortable evaluating and adopting solutions internally.
The result, as Shopify sees it, supports both inclusive culture and asynchronous work: information is accessible anytime, anywhere, on any device.
Building Useful Technical Docs
Documentation can be difficult to track for health. There's no unit test for quality. To ensure the content stays both readable and actively maintained, Shopify suggests focusing on these three components:
- Integrate documentation content into existing CI/CD systems. When docs go through test and deployment the same way as code, the effort to produce them declines. Immediate feedback from a pipeline encourages engineers to contribute knowledge as part of ongoing code work.
- Place docs where engineers already work. The principle works best when the settings are familiar. Allowing engineers to edit docs directly within their existing code review workflows, whether on GitHub or GitLab, means less context switching.
- Prioritize usability and aesthetics. Docs need to be engaging and readable in order for knowledge to be absorbed. Formatting for legibility and a visually clean structure are essential to retaining the information—and general usability drives better day-to-day outcomes.
Maintaining a Writing Habit
Starting to write about their own projects can be intimidating for an engineer. Building the habit, Shopify suggests, begins small. A few practical steps are common:
- Use regular, small tasks like bug tickets and smaller features as writing opportunities, rather than waiting for a large project to document.
- Pair with teammates to co-author documentation. Collaboration often brings in more complete context, produces fresh viewpoints and strengthens the end result.
- Always adapt the writing to fit the context and audience. Adjusting the inclusion level of background information—with depth aimed at the people from whom the information is most relevant—increases the quality of articles from platform to platform.
Writing is ultimately an engineering skill that can be built over time, like code. By rewarding a culture that documents for understanding as well as implementation, other teams can see benefits almost immediately: better cross-team contributions, easier first moves into unfamiliar repositories, and more durable institutional knowledge footprint.
