Walking through all the steps in documentation yourself is critical to producing high-quality, accurate instructions. But 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.
I believe so strongly in testing API doc content that I’ve created an entire section devoted to this topic. This section includes three topics:
Many times developers don’t expect that a technical writer will be doing anything more than just transcribing and relaying the information given to them. With this mindset, a developer might not immediately think that you need or want a sample app to test out the calls or other code. You might need to ask (or even petition) them for it.
Most of the time, developers respect technical writers much more if the technical writers can test out the code themselves. Engineers also appreciate any feedback you may have as you run through the system. Technical writers, along with QA, are usually the first users of the developer’s code.
If a developer or QA person can’t give you access to any such test server or sample code, be suspicious. How can a development and QA team create and test their code without a sample system where they expect it to be implemented? And if there’s a sample system, why can’t you also have access so you can write good documentation on how to use it?
Sometimes developers don’t want to go through the effort of getting something working on your machine, so you may have to explain more about your purpose and goals in testing. If you run into friction, be persistent. Once you have a test system set up, it makes it much easier to create documentation, because you can start to answer your own questions.
27/91 pages complete. Only 64 more pages to go...
Get new posts delivered straight to your inbox.
© 2017, Tom Johnson