Stay updated
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 6,100+ subscribers. (See email archive here.)

Search results

I'd Rather Be Writing blog

Should you add your testing scenarios into your documentation?
Should you add your testing scenarios into your documentation?
When you test a product, you usually put together simple test scenarios that include actual values and other specific details. You can repackage these test scenarios into documentation-based tutorials that help users understand how to use the product. By including specific values and instruction with a defined end, new users can better understand how to use the product for different use cases and scenarios.
Peter Gruenbaum has released part 2 of his Udemy course on API technical writing
Peter Gruenbaum has released part 2 of his Udemy course on API technical writing
If you want to learn how to document REST APIs, consider taking Peter Gruenbaum's courses on Udemy. He recently released part 2 of his REST API tech writing course. Part 2 gets into the meat of writing reference documentation for REST APIs.
Survey results about the possible REST API workshop
Here are the survey results from my survey I conducted about a possible REST API workshop. Although a workshop would have a lot of appeal, many people are interested in online options since they aren't located in the area where I would give the workshop.
Is it inefficient to frequently switch contexts among multiple projects?
Although the ability to juggle multiple projects is common to the technical writer role, switching contexts can hurt your momentum with projects because each time you switch, you have to re-prime your memory pump with a hundred details about the project. At the same time, this mental reset can help you see the product fresh, like a new user. In that respect, context-switching can be helpful.
Survey about possible REST API workshop — your feedback would be helpful
These survey questions will help me better prepare for a possible workshop on API documentation.
Getting mobile friendly display and responsive design just right, especially with ads
Not having a mobile friendly display for your site not only strains readers on mobile devices, it can hurt your SEO. Making your site mobile friendly also poses some unique challenges with advertising slots, because the slots shift around when you switch from desktop to mobile.
Reader question: How do I move forward out of a stagnant tech writing career?
To move out of a stagnant career, immerse yourself in learning on your own. You can learn programming online, for example, or specialize in a knowledge domain or tools.
Should technical writers care about more than documentation?
As a technical writer, your holistic understanding of the total customer journey allows you to extend beyond your doc-writing role to wear other hats with usability, quality assurance, product management, training, support, and more. But the more time you spend in these other roles, the less time you have to spend on documentation, which results in a weaker doc product.
Build a technical writing portfolio by writing documentation for startups
People looking to break into technical writing are often looking for open source projects they can document in order to build their technical writing portfolio. Instead of looking for open source projects, check out to find startups that might need help with documentation.
Communicating feedback from testing documentation
After testing your documentation, you should communicate the feedback with your project teams. As much as possible, try to communicate the information through issue tracking systems because this makes the information more permanent, visible, and actionable.
Guest post: 10 New Things to Love and Hate About Flare
In this guest review about the latest version of Madcap Flare, Karen Rempel reviews an older post I wrote about Flare 7 years ago and re-evaluates the points I loved or hated with the new version of Flare in mind.
Should QA test documentation?
The past few years, I've allowed doc to be treated as an external product, separate from the software engineering code. In reality, doc would probably benefit tremendously from a more strict integration with the engineering code review cycles, with the review split between QA and product management.
Listen to Ed Marsh's Content Content podcast with me as a guest
Ed Marsh had me as a guest on episode 4 of his Content Content podcast, which is now available to listen to.
The key to writing good documentation: Testing your instructions
The key to writing good documentation: Testing your instructions
Writing good documentation requires you to set up a test environment and test all of your instructions -- testing the instructions yourself and against a user. Testing instructions can be time consuming and tricky, especially with developer documentation. It's hard to see past personal blind spots and assumptions. But testing instructions gives you access to insight that makes your documentation much more accurate and useful.
Pingdom reports with WordPress on Bluehost/MaxCDN versus with Jekyll on Github
My blog is both faster and more stable with Jekyll on Github than it was with WordPress on Bluehost with MaxCDN.