Overview of testing your docs
Up until now, you’ve been focused intensely on API documentation. In this section, I’ll talk about an aspect of API documentation that is perhaps more applicable to all types of documentation but which is especially relevant to developer docs, where testing and experimenting with the products and services is not always straightforward.
Walking through all the steps in documentation yourself is critical to producing high-quality, accurate instructions. The more complex setup you have, the more difficult it can be to test all of the steps. Still, if you want to move beyond merely editing and publishing engineer-written documentation, you’ll need to build sample apps or set up the systems necessary to test the API docs. These tests should mirror what actual users will do as closely as possible.
Leveraging test cases from QA
When you start setting up tests for your documentation, you typically interact with the quality assurance (QA) team. Developers might be helpful too, but the quality assurance team already has, presumably, a test system in place, usually a test server, and test cases. “Test cases” are the various scenarios that the product needs to be tested against.
You’ll want to make friends with the quality assurance team and find out best practices for testing scenarios relevant to your documentation. They can usually help you get started in an efficient way, and they’ll be excited to have more eyes on the system. If you find bugs, you can either forward them to QA or log them yourself in the team’s issue tracker.
If you can hook into a set of test cases that QA teams use to run tests, you can often get a jump start on the tasks you’re documenting. Good test cases usually list the steps required to produce a result, and the scripts can inform the documentation you write.
Ways to test content
Testing your API doc content is so critical, I’ve created an entire section devoted to this topic. This section includes three topics:
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.
61/166 pages complete. Only 105 more pages to go.