The first step to testing your instructions is to set up a test environment. Without this test environment, it will be difficult to make any progress in testing your instructions.
The type of test environment you set up depends on your product and company. In the following sections, I explain testing setup details for different scenarios:
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 they’re testing.
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.
If you can hook into a set of test cases 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.
With the test system, you’ll need to get the appropriate URLs, login IDs, roles, etc., from QA. Ask if there’s anything you shouldn’t alter or delete because sometimes the same testing environment is shared among groups. Make sure your logins correspond with the permissions users will have. If you have an admin login, you might not experience the same responses as a regular user.
You may also need to construct certain files necessary to configure a server with the settings you want to test. Understanding exactly how to create the 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.
Exactly what you have to do depends on your product, the environment, the company, and security restrictions, etc. No two companies are alike. Sometimes it’s a pain to set up your test system, and other times it’s a breeze.
Many times, developers work on local instances of the system, meaning they build the app or web server entirely on their own machines and run through test code there. To build code locally, you may need to install special utilities or frameworks, become familiar with various command line operations to build the code, and more.
If you can get the local builds running on your own machine, it’s usually worthwhile because it can empower you to document content ahead of time, long before the release.
If it’s too complicated to set up a local environment or to access a test server, ask an engineer to install the local system on your machine. Tell him or her that, in order to write good documentation — documentation that is accurate, complete, and doesn’t assume anything — you need access to these test systems.
If the setup to build locally is complex, you may need to ask a developer for help. Sometimes, developers like to just sit down at your computer and take over the task of installing and setting up a system. They can work quickly on the command terminal and troubleshoot systems or quickly proceed through installation commands that would otherwise be tedious to walk you through.
At one company, to gain access to the test system, we had to jump over a series of security hurdles. For example, connections to the web services from internal systems required developers to go through an intermediary server. So to connect to the web server test instance, you had to SSL to the intermediary server, and then connect from the intermediary to the web server. (This wasn’t something users would need to do, just internal engineers.)
The first time I attempted this, I asked a developer to help me set this up. I carefully observed the commands and steps he went through on my computer. I later documented it for future knowledge purposes, and other engineers used my doc to set up the same access.
Many times, developers aren’t too motivated to set up your system, so they may give you a quick explanation about installing this and that tool. But never let a developer say “Oh, you just do a, b, and c.” Then you go back to your station and nothing works, or it’s much more complicated than he or she let on. It can take persistence to get everything set up and working the first time.
If a developer is knee-deep in sprint tasks and heavily backlogged, he or she may not have time to help you properly get set up. Be patient and ask the developer to indicate a good time to go over the setup.
With local builds, setting up a functional system is much more challenging than using a test server. Still, if you want to write good documentation, setting up a test system is essential. Good developers know and recognize this need, and so they’re usually accommodating (to an extent) in helping set up a test environment to get you started.
Depending on the product, you might also have a sample app in your code deliverables. You often include a sample app (or multiple apps in various programming languages) with a product to demonstrate how to integrate and call the API. If you have a test app that integrates the API, you’ll probably need to install some programs or frameworks on your own machine to get the sample app working.
For example, you might have to build a sample Java app to interact with the system. If the app is in PHP, you may need to install PHP. Or you may need to download Android Studio and connect it to an actual device.
There’s usually fewer instructions about how to run a sample app because developers assume users will already have these environments set up on their machines. (It wouldn’t make sense for a user to choose the Java app if they didn’t already have a Java environment, for example.)
The sample app is among the most helpful pieces of documentation. As you set up the sample app and get it working, look for opportunities to add documentation in the code comments. At the very least, get the sample app working on your own computer and include the setup steps in your documentation.
If you’re documenting a hardware product, you’ll want to secure a device that has the right build installed on it. Big companies often have prototype devices available. At some companies, there may be kiosks where you can “flash” (quickly install) a specific build number on the device. Or you may send your device’s serial number to someone who manages a pool of devices included in certain updates from the cloud.
With some hardware products, it may be difficult to 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 was allowed to see the storage array was by signing into a special data server room environment, accompanied by an engineer, who wouldn’t dream of letting me actually touch the array, much less swap out a storage disk, run commands in the terminal, replace a RAID, or do some other task (for which I was writing instructions).
I learned early on to steer my career towards jobs where I could actually get my hands on the product, usually software code, and play around with it. If you’re documenting hardware, you need access to the hardware to provide reliable documentation on how to use it. You’ll need to understand how to run apps on the device and interface with it. Hopefully, the product is one that you can access to actually play around with.
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. It might take one or more days to get your test environment set up. 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.
After you get the test environment set up, it’s time to test your instructions.
29/92 pages complete. Only 63 more pages to go...
If you would like to contribute back to say thank you for the API documentation course, click the Donate button below. Alternatively, to contribute content, such as a tutorial or a new section, contact me with your ideas. You can also submit a pull request in the GitHub repo to make your contribution. Even if you want to just fix a typo or add a sentence here and there, it's always welcome.
Get new posts delivered straight to your inbox.
© 2017, Tom Johnson