Test driving the documentation
One of the most effective practices I've found for documentation is something I call test-driving.
A test drive is when you follow the steps yourself in any procedural documentation and verify that they work the way you think they do. After a test drive the documentation is far more accurate and useful than documentation that has not been tested. (This works even if you're the engineer who wrote the software.)
It's especially effective for developer-facing docs, like API reference and API how-to articles, but test driving is worthwhile for any technical documentation.
I don't know how much technical writing is tested this way, but I'm certain that test-driven docs are superior and that not everyone tests.
How I started
My first test drive took place shortly after I began working on the documentation for a command line tool.
I transferred every step-by-step procedure in the docs to a spreadsheet. Every step became a row, and there were columns for expected outcome, pass/fail, and notes.
I followed the steps in the documentation, and if the step worked the way the docs said, the step passed. If not, I made some notes about how the docs needed to be updated.
The project resulted in updating a handful of code samples and even uncovered a couple of bugs in the software. The steps had never been tested and in one or two steps, the software wasn't working as intended at the time I did the test.
It was easy to justify the day or two I spent on this testing to management. After the test drive I sent an email detailing the number of doc improvements and bugs that were fixed.
Using a spreadsheet made it easy to compile metrics about how many steps passed or failed, and how many errors were found, but it isn't mandatory. The simplest way to go is just follow the procedure and take notes about anything you learn.
Nowadays, I don't use a spreadsheet and I've never tested a complete guide again. I test one topic at a time, as I go.
APIs and test driving
When writing a non-reference, step-by-step workflow (a how-to article) that covers several API calls, a test drive is indispensable. It gives you a chance to discover the common mistakes, to point out easily overlooked but required parameters, and to remind users of data they need to collect from a response because it will be needed for a later step.
On each step of an API procedure, you can start with the example given in the reference docs (if you have Swagger or something similar to generate an example) and modify it for the purposes of your procedure. This makes you use the software and the reference docs in the way a customer would.
You'll find out quickly whether the mandatory parameters have been identified correctly and whether attributes work as expected.
What test driving doesn't do
Keep in mind that test driving doesn't replace any of the following:
User testing or usability testing. Those require interaction with real customers and they’re intended to provide insights into the customers’ behavior and requirements. A test drive addresses the authors understanding of a task before documenting it.
Engineering review of documentation, which is always necessary.
QA review of documentation.
Other research methods, like interviewing engineers, reading specs, or attending scrum meetings.
Test driving adds a new capability that is different from any of these things.
Setting it up
Here are some thoughts about how to begin.
Make sure you have plenty of time for the extra work involved in a test drive. It's not something to do for the first time if you are experiencing the manic part of a stressful release process. And when you do adopt test driving, expect certain writing tasks to take up more time.
You need access to a test environment with the latest features that are in development. The production version won't have unreleased features. Your QA team most likely maintains a version of the application with the latest builds, and you can ask for access if you don't have it.
If you're a technical writer new to the company or new to test driving, get going by following the product's "Getting Started" documentation first. You'll become comfortable with using it like a customer, and you might make note of some needed improvements while you do that. After you're comfortable using the product and know you can access the new features quickly, make the test drive a regular part of the documentation process.
Conclusion
Most people who use software are unhappy with it, and largely because the documentation isn't that helpful. Software documentation is a relatively new field and it still has a long way to go.
Test driving is one of the few practices where the improvement is immediate and noticeable to people outside of your team, including customers. If you don't test drive, and you have time to do it, get started.