How Good Documentation Can Improve Productivity

Good documentation has many benefits, but first and foremost it boosts engineers’ productivity. Here are a few tips to encourage a strong writing culture.

Shopify logo
Shopify
•
Michael Chemani
•9 min read•beginner•
--
•View Original
GitGitLabVault

Overview

The article discusses the importance of good documentation in improving productivity within engineering teams, particularly at Shopify. It highlights the challenges of poor documentation and outlines strategies for creating effective internal documentation that enhances knowledge sharing and collaboration among engineers.

What You'll Learn

1

How to create effective internal documentation that enhances productivity

2

Why a strong documentation culture is essential for engineering teams

3

When to prioritize documentation over coding tasks

4

How to use tools like GitHub and Docusaurus for documentation

Key Questions Answered

How does good documentation improve productivity in engineering teams?
Good documentation streamlines information access, reducing the time engineers spend searching for knowledge. It prevents the need to reinvent the wheel by providing clear examples and processes, thus enhancing overall productivity and collaboration.
What tools does Shopify use for internal documentation?
Shopify uses several tools for internal documentation, including Markdown documentation powered by Docusaurus, GitHub for tracking issues and project information, and The Vault as a central repository for contextual information. These tools help maintain a comprehensive and accessible documentation culture.
Why is documentation considered a product at Shopify?
Documentation is treated as a product at Shopify to emphasize its importance and ensure it is well-maintained and user-friendly. This approach encourages engineers to contribute actively, making documentation a collaborative effort that benefits the entire organization.
What are the benefits of a strong documentation culture?
A strong documentation culture boosts productivity, enhances onboarding processes, fosters inclusivity, and encourages collaboration across teams. It allows engineers to access information independently, reducing reliance on others and speeding up project timelines.

Technologies & Tools

Some links below are affiliate links. We may earn a commission if you make a purchase.

Documentation Tool
Docusaurus
Used for creating Markdown documentation websites that are easy to maintain and update.
Version Control
Github
Serves as a bug/ticket/issue tracker and a source of project documentation.

Key Actionable Insights

1
Standardize documentation practices across teams to enhance consistency and accessibility.
By creating a uniform approach to documentation, teams can ensure that all engineers have access to the same quality of information, which can significantly reduce onboarding time and improve overall productivity.
2
Encourage engineers to document their processes and solutions as part of their workflow.
Integrating documentation into the development process not only helps preserve knowledge but also fosters a culture of sharing and collaboration, making it easier for teams to learn from each other's experiences.
3
Utilize tools like GitHub and Docusaurus to streamline documentation efforts.
These tools provide familiar environments for engineers, making it easier to contribute to documentation while also ensuring that the information remains close to the codebase, which enhances discoverability.

Common Pitfalls

1
Neglecting documentation in favor of coding tasks can lead to knowledge silos.
When engineers prioritize shipping code over documenting processes, it creates gaps in knowledge that can hinder team collaboration and slow down onboarding for new members.
2
Failing to keep documentation updated can render it useless.
Outdated documentation can mislead engineers and lead to wasted time searching for information or implementing incorrect solutions, highlighting the need for regular reviews and updates.