Craft Docs

Writing, code, and internal processes that improved product documentation.

Challenge

The expanding Craft CMS documentation covered several products maintained by different people, resulting in stale and missing content, varying tone, and an ongoing challenge to maintain.

Steps Taken

  • Consolidated disparate, versioned product documentation into one code base.
  • Overhauled the underlying VuePress project to feel more on brand, with customizations to improve structure, clarity, and readability.
  • Enhanced reference material with refinements to generators and CI pipelines that narrow the gap between documentation and source code.
  • Wrote a self-contained “getting started” tutorial for beginner onboarding.
  • Introduced automated testing and linting to help with consistency.
  • Responded to issues raised in GitHub, Discord, and support tickets.
  • Documented repositories and pipelines responsible for all public documentation.
  • Coordinated internally to document changes with increasing efficiency.

Result

The documentation felt more on-brand, became more consistent across products, and kept pace better with product development. My efforts at internal coordination led to discussion about shifting into a project management role.

[object AsyncGenerator]
Split screenshot of the Craft documentation illustrating light and dark mode, and with navigation for Craft CMS, Craft Commerce, and Craft Nitro
One landing for different product documentation.
[object AsyncGenerator]
Tightly cropped screenshot of a “Was this helpful?” widget in a page footer, with thumbs up and thumbs down buttons
Voting encourages PRs and tracks feedback with Google Analytics events.
Screenshot of the documentation landing, with a search for “install” listing results for Craft CMS, Craft Commerce, and Craft Nitro
Custom search adapts to the selected product and version, or searches across the most recent product versions from the landing.
[object AsyncGenerator]
Tightly cropped screenshot of a small banner that reads “This document is for an older version of Craft CMS” with a link to view the latest version
Each product alerts search traffic to newer documentation for major versions. Equivalent content can be maintained when switching versions, even if the URLs differ.
[object AsyncGenerator]
Tightly cropped screenshot of a console command whose last argument (`path/to/my-project`) is styled with a little box, whose mouseover title reads “Replace this with your project path.”
Common placeholder values are automatically emphasized.