In May, I attended the Write the Docs conference in Portland to meet with a global community of people who write documentation: programmers, product managers, tech writers, etc. I listened to speakers talk about various topics like writing scenario-based documentation, continuous deployment, open source documentation, and what I learned was that our docs rock.
Is it wrong to boast about our awesome docs site? I hope not, because I’m really proud of what the Pantheon team and our customers have built—and we did it the right way.
How we did it:
1. Open source documentation
The first step was migrating the entire docs site from a CMS built into our support ticketing system to Sculpin. This project entailed scraping the existing docs, converting them to markdown, defining a new information architecture, building and designing the Sculpin site, moving all images, and managing images so that they appear in the markdown on GitHub and on the deployed output. It’s still a work in progress, and if you want to help with technical suggestions or improvements, please create an issue or submit a pull request.
Once it was ready, we made our documentation site's repository public on GitHub. The site is built with Sculpin and deployed to the /docs subdirectory of our Pantheon.io site. Each doc includes a link that takes you to GitHub to edit it. If you don’t have time to edit a doc, you can always create an issue in the issue queue to let us know which docs need updates or to submit ideas for new docs.
Doing it this way allows anyone to update a doc—no more limiting it to internal resources—a problem most companies face. Internal resources have the knowledge, but their time is often limited.By making our documentation public, our docs will continue to improve thanks to the wealth of knowledge in our community of developers, along with their willingness to share it.
2. Easy to access and use the tools
Forget XML, DITA, and the complex authoring tools they require to create docs. GitHub is accessible by everyone with an account, and its simple GUI makes it easy for contributors to create issues or submit pull requests on new and existing docs.
Prefer using the command line? Fork our site and use the editor of your choice. Then push your changes to our repo via Git.
This also simplifies the review process, which means docs get published at a faster pace.
3. Clean, minimalist design
Our goal is to make it easy for you to find the information you need. Most people agree that less is more, and our docs site achieves this by reducing the design to only the most essential elements. We made the search bar prominent and offer a few options to help you get to the information you need.
There is this one thing…
Of course, nothing is ever perfect and there is always room for improvement. During the conference almost every presenter talked about their company’s documentation issues. The number one issue we all share is stale docs (outdated content). When there are hundreds of docs, it’s a challenge to keep track of each one that needs to be updated when the code changes or new features are released. It’s a problem we all struggle with solving, but we’re working on it by humbly asking for your help by contributing to our docs and sending us your feedback.
We’ll continue working out the kinks and striving to create accurate, relevant documentation. Open source documentation is an innovative way to do it. Let’s keep rocking the docs!
Topics: Guides and Tutorials, Training and Education, Education, Drupal, WordPress