Email Newsletter

Search results

I'd Rather Be Writing blog

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.
Three questions people ask me each week
About once a week I get the following three questions. It would be nice to see some more variety.
Slides, notes, and lessons learned at the STC Summit 2015 in Columbus, Ohio
I recently attended the STC Summit 2015 in Columbus, Ohio. I gave both a workshop and presentation on REST API documentation. This post includes my slides, links to notes, and some thoughts.
My upcoming workshop and presentation at the STC Summit 2015 in Columbus, Ohio
I'm giving both a workshop and presentation at the STC Summit in Columbus, Ohio. I'm also receiving an award for oustanding guest-edited issue of the Intercom.
How to avoid early death from sitting down all day
Sitting down all day creates serious health risks. You can avoid an early demise through a little counter app that reminds you to take a break every 20 minutes.
How do you authenticate your documentation?
Authenticating documentation poses significant challenges with identity access control. Ideally, customers should only see documentation for products they purchased. Rather than creating separate sites for each audience, a content management system can map viewing rights to user groups.
Check out my conversation on ContentHug
ContentHug is a content curation service focused on tech comm. Currently the site has a theme of conversations with various tech comm pros, mostly about content strategy.
How can technical writers cut through engineering jargon and decode complex information?
As technical writers, we know our task is to explain how complex products work through simple, easy-to-understand language. But before you can explain something, you first have to decode that complexity for yourself. You can decode complexity by approaching it piece by piece, asking engineers for details, drawing pictures, experimenting, and more.