Advent of Technical Writing: Authoring Tools

This is the sixteenth post in the Advent of Technical Writing series, wherein I will share something I have learned from my experience as a technical writer. My experience is primarily in software technical writing, but what you read may apply to different fields, too. View all posts in the series.

When someone contributes a blog post or documentation to the Roboflow website, we ask that they write their contributions in specific tools. For blog posts, we ask that contributions are delivered in a Google Document. For product documentation, we ask that the documentation is written in GitBook, our documentation tool of choice. For open source documentation, we ask that documentation is in a PR so that it can be reviewed alongside any code that has changed.

Directing contributors to use specific tools

We ask contributors to use specific tools for two reasons:

1. It reduces ambiguity in the publishing process, and;
2. We, the content team, can ensure that all content is contributed in a tool in which we are able to provide collaborative feedback.

Reducing ambiguity in publishing is essential. To the extent we can keep the process standard, we do. At Roboflow, we used to allow people to write Google in our CMS directly or in a Google Document. With no clear directive, content was delivered in both tools. Because our CMS has inferior editing tools to a Google Document, providing feedback was harder. This was a significant issue. Our editing process is hands-on; we strive to give people detailed feedback on their work. Our CMS limits our ability to do this.

Indeed, CMS's are mainly designed for publishing not collaborative authoring. By opting for collaborative tools where possible, we, the content team, can be more expressive and detailed in our feedback.

Tool choices

For blog posts, Roboflow asks contributors to author documents in Google Documents ('Google Docs'). The editing interface provides an extensive set of features that overlap with what we need for our blog posts. Furthermore, Google Docs provides a strong set of collaborative features that are important to the content team. Multiple people can edit a document at once, reliably. We can leave comments inline that can be accepted or rejected with the click of a button.

For product documentation, contributors are asked to work directly in our documentation tool. This is because changes can involve a lot of custom formatting. For example, a contributor might adding API specifications, code snippets with multiple tabs, etc. Rather than write in a separate tool, we empower team members to write directly in the documentation so they can mark it up as necessary. We ensure all team members have access to our tool if they want to make a change, provide guidance on how to make a change if required, and answer any questions along the way.

For open source documentation, we collaborate on our documentation in GitHub. We ask that documentation is provided with new feature changes. Documentation is a requirement for shipping. I usually do documentation reviews and provide comments using the PR review tool available in the GitHub web interface. I leave all my suggestions as "Comments" to ensure that my editorial notes do not constitute approval for the code in a PR. This is essential. Documentation review is not a code review.

These are our tool choices, but the tools you use may vary. Indeed, you should choose the tool that works best for your team. Importantly, the tools in which content is delivered to an editor should empower editors, for editing is their role. If a team member writes a document in a tool with which an editor is not familiar, the editor will likely have to move the contents into another tool. This is less than ideal, introducing the potential for content to be accidentally modified during the move between tools.