Description
We call ourselves technical writers, but many of us spend more time editing the work of others than writing ourselves. When you have a large team or a large product (or both!), the cooks in the documentation kitchen come from all parts of the company: marketing, product, engineering, sales, and more. This adds a significant burden on you and your team to make sure the content they produce is accurate, fits within your style guide, uses the correct tone, and doesn''t add additional confusion.
At Mapbox, we have both a large team and a complex product, which means many different writers with individual writing styles and varying depth of knowledge of the product. To keep our work accurate and unified under a common voice while avoiding breaking our necks with editing, we implemented an automated content testing system (fully open source!) to do some of the work for us. Automated tests have helped us embed quality writing and editing into the development process as much as code testing does. "It''s not finished until it''s documented" is more than just a happy thought -- it''s now an immovable part of our workflow.
In this talk, I will discuss the reasons you might want to implement an automated testing system in your organization, examples of how it''s been beneficial, the story of how we set up our system, and a brief overview of the tools that exist for doing this work. I''ll also cover the ways that automated tests can sometimes make funny mistakes and how we found the balance between making tests too precise and not precise enough. For those who are interested in implementing right away, I will also provide a comprehensive list of resources for getting started.