testing_documentation 1.0 → The key to writing good documentation: Testing your instructions 1.1 Should QA test documentation? 1.2 Communicating feedback from testing documentation 1.3 Should technical writers care about more than documentation? 1.4 Should you add your testing scenarios into your documentation? 1.5 How do you test content that's beyond your skill level? 1.6 Podcast: How do design, length, and relevance affect how people use API reference docs — interview with Bob Watson You can download the MP3 file here. Testing overview Recently, in the rush to meet deadlines, I had to put aside one of the principles of technical writing I value the most: testing all the steps in my documentation, exactly as a user would. Walking through all the steps in documentation yourself, as a technical writer, is critical to producing good documentation. But the more complex setup you have, the more difficult it can be to walk through all of the steps. Especially with developer documentation, the tasks are not trivial. Still, they are essential to creating user-centered documentation. Step 1: Set up a test environment The first step to testing your instructions is to set up a test environment. Usually the QA team already has this environment in place, so sometimes all you need to do is ask how to access it. Get the appropriate URLs, login IDs, roles, etc. from your QA team. Ask them if there's anything you shouldn't alter or delete, since sometimes the same testing environment is shared among groups. Without this test environment, it will be really difficult to make any progress in testing your instructions. Although the test environment seems like a no-brainer, it really isn't. A lot of times, developers test systems on their local machines, so setting up a web instance requires someone to get a server, install the latest build, and give you access to it. Other times the platform requires extensive architecture to set up. For example, you might have to build a sample Java app to interact with the system. Setting up these resources on your own machine may prove challenging. If you're documenting a hardware product, you may not get a test instance of the product to play with. I once worked at a government facility documenting a million-dollar storage array. The only time I ever got to see it was by signing into a special data server room environment, accompanied by an engineer, who wouldn't dream of letting me actually touch the thing, much less swap out a storage disk, run commands in the terminal, replace a RAID, or do some other task for which I was supposedly writing instructions. Many times the QA and engineering teams work on local instances of the system, meaning they build the system on their local machines and run through test code there. You may need to submit a special request for an engineer to put the latest build on a server you can access. Sometimes you may also have to jump over security hurdles. For example, connections to Amazon Web Services from internal systems may require you to go through an intermediary server. So to connect to the AWS test instance, you would have to SSL to the intermediary server, and then connect from the intermediary to AWS. You may also need to construct certain YML files necessary to configure a server with the settings you want to test. Understanding exactly how to create the YML files, the directories to upload them to, the services to stop and restart, and so on can require a lot of asking around for help. When you're ready to submit a test call (assuming you have a REST API), you can probably use cURL, which makes it easy, but you'll no doubt need to include an authorization in the header of the call. The authorization often uses a hash of a combination of factors. Can you see how just getting the test system set up and ready can be challenging? Still, if you want to write good documentation, this is essential. Good developers know and recognize this nee