No great masterpiece was ever created in a vacuum. Every work of art, engineering feat, and product release results from inspiration, ideas, and feedback from others.
Technical writing is no exception. While many may think that technical writing is done by a lone writer who is given some early specs and asked to “pretty them up” and publish them, nothing can be further from the truth.
Good technical writers understand that their job is to gather insight and information from a diverse set of people and turn what may be a mountain of facts into a molehill of factual, informative, and useful content.
How’s that done? Collaborating with product owners, UI/UX designers, developers, marketing managers, support technicians, and – most importantly – readers. Each audience has a different viewpoint on what people need to know. Each has a different level of experience with the subject at hand. Some are newbies; others are experts.
The Process
Technical writers have unique needs when it comes to collaboration. Most writers support multiple products and teams, so they need the flexibility to go into a project at different stages. They need access not only to requirements and design documents but too early versions of the product or technology they’re documenting. Finally, they need time to mentally process all this information before they can write meaningful content.
To ensure this process works well for everyone, here are some tips for collaborating with technical writers.
1. Get them involved early.
Technical writers abhor coming into projects at the end. Why? Most often, they’re your first end-users. Because they have to explain how things work clearly, they tend to find design flaws pretty quickly. If you bring them in at the last minute, you’re losing valuable insight that can improve quality and customer satisfaction.
Also, consider that most technical writers are reference librarians for your product. Here’s a common type of question you’ll hear from technical writers: “I see you’re calling this new thing’ widgets.’ Is that related to the ‘widgets’ added by team X last year?” Best to hear that early on in the release cycle rather than at the end.
2. Add documentation requirements to the project plan.
Every project is different. Some projects need a bit of UI text; others need detailed API or integration documentation. While you don’t need a detailed documentation plan for every project, discuss the needs upfront to prevent some headaches later.
3. Pick a standard style guide, then stick to it.
Feedback is excellent, but to ensure that it’s as useful as possible, make sure you use standards for our content.
Stoplight provides style guides for Open API documents that combine industry best practices with your organization’s unique needs. Stoplight automatically validates your API documents as you work with them, ensuring they are ready for more meaningful feedback at review time.
For other content, follow an industry standard and only deviate from it for your company terminology. Stoplight technical writers follow the Microsoft Style Guide, but there are others (Google, Chicago, and Associated Press, to name a few.) Bonus points: use tools such as Vale to enforce industry standards and create rules for the company- and product-specific standards.
The style guide you choose is less critical than consistently following the standards. Product teams are expensive, so make sure feedback is focused on larger goals rather than tried-and-true guidelines. We have a great guide if you need more tips on style guides.
4. Don’t scrimp on reviews.
Establish a review process, then follow it. If technical accuracy is critical to your readers, make sure that someone with in-depth knowledge reviews content before it ships. If clearly articulating a business case is most important, get a product owner or marketing person involved. Don’t treat reviews as a last-minute task; give reviewers time to read and process the material.
Another valuable process that companies often forgo is peer reviews by other technical writers. These reviews aim for someone not as close to the content to take a holistic view. Is the content easy to understand? Is it well organized? Does it flow nicely with other content?
5. Track and act on feedback.
If you don’t act on it, there’s no point in taking in feedback. Whether you get direct feedback from internal stakeholders or customers or use tooling and automation to gather questions and requests, ensure you track what comes in and how it’s addressed.
There are countless ways to do this. Stoplight uses ZenHub issues to track documentation feedback, no matter how small or large. Stoplight’s development teams also use ZenHub, so it’s an easy and familiar way for product teams and stakeholders to see what’s coming in and how we’re addressing it. We’ve also developed service-level agreements to establish guidelines for how quickly feedback is addressed.
The Result
Hopefully, these tips will help you take your technical content from one-way
collaboration with your stakeholders and customers to an ongoing process for improving the information you share with the world. For more resources for tech writers, I suggest the following:
- Open-source documentation tooling with Elements
- A Tech Writer’s Experience with Stoplight
- Documenting in Stoplight Platform
