---
title: "How Good Documentation Can Improve Productivity"
description: "Internal documentation is presented as a productivity and scaling tool for engineering organizations, especially as people move between teams, projects, or companies and remote work makes writing a default channel for knowledge sharing. Shopify’s approach combines standardized writing practices with three primary locations: Markdown microsites built with Docusaurus, internal GitHub for issues, READMEs, setup guidance, and searchable code, and the Vault, a GitHub- and Markdown-powered source of contextual information. The article argues that documentation should be treated as a product: it should be searchable, user-friendly, kept fresh, integrated into CI/CD, and hosted where engineers already work. It also recommends making writing routine through small contributions, paired writing, peer review, and audience-aware context, concluding that accessible documentation speeds onboarding, reduces duplicated problem-solving, supports asynchronous and cross-team collaboration, and improves developer literacy."
---

# How Good Documentation Can Improve Productivity

[Shopify](https://yomu.fyi/company/shopify) · 2023-10-18 · Jan 12, 2023

**Type:** Explainer

## Summary

Internal documentation is presented as a productivity and scaling tool for engineering organizations, especially as people move between teams, projects, or companies and remote work makes writing a default channel for knowledge sharing. Shopify’s approach combines standardized writing practices with three primary locations: Markdown microsites built with Docusaurus, internal GitHub for issues, READMEs, setup guidance, and searchable code, and the Vault, a GitHub- and Markdown-powered source of contextual information. The article argues that documentation should be treated as a product: it should be searchable, user-friendly, kept fresh, integrated into CI/CD, and hosted where engineers already work. It also recommends making writing routine through small contributions, paired writing, peer review, and audience-aware context, concluding that accessible documentation speeds onboarding, reduces duplicated problem-solving, supports asynchronous and cross-team collaboration, and improves developer literacy.

## Context

Internal documentation can be time- and money-consuming, scattered across platforms, difficult to keep current, and often deprioritized relative to shipping code. Poor documentation leaves knowledge in individuals’ heads, makes codebases and project setup harder to navigate, and creates particular challenges as engineers change teams or work across time zones.

## Approach / What changed

Shopify standardizes how internal documentation is written and treats it as a product. Its main tools are Markdown microsites powered by Docusaurus, internal GitHub for issues, READMEs, setup guidance, and searchable code, and the Vault, a GitHub- and Markdown-powered platform for contextual information. The article recommends integrating documentation into CI/CD, keeping it in familiar and searchable tools, making it user-friendly, and encouraging contributions through small tasks, paired writing, and attention to audience and context.

## Takeaways

- Shopify uses Docusaurus-powered Markdown microsites, internal GitHub, and the Vault to publish and discover technical knowledge.
- Documentation integrated into CI/CD and hosted in tools engineers already use can make writing and searching more accessible.
- The article connects accessible documentation with faster onboarding, less duplicated problem-solving, asynchronous communication, and stronger cross-team collaboration.

**Tags:** [CI/CD](https://yomu.fyi/topic/ci-cd), [Developer Experience](https://yomu.fyi/topic/developer-experience), [Onboarding](https://yomu.fyi/topic/onboarding), [Remote Work](https://yomu.fyi/topic/remote-work)

- Source: [Shopify](https://shopify.engineering/good-documentation-productivity)
- Source URL: https://shopify.engineering/good-documentation-productivity
- Ingested by Yomu: 2026-08-30T13:36:17.823Z

[Read original post](https://shopify.engineering/good-documentation-productivity)