Ed Marsh had me as a guest on episode 4 of his Content Content podcast, which is now available to listen to.
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.
My blog is both faster and more stable with Jekyll on Github than it was with WordPress on Bluehost with MaxCDN.
About once a week I get the following three questions. It would be nice to see some more variety.
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.
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.
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.
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.
Girls Make Games is game programming camp for girls. My daughter participated in it last year, and the game she and her team made is now available to download.
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.
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.
I hosted a technical writing booth at my 8th-grade daughter's career fair day, but almost no one stopped by. Deflated, I tried to analyze why. I realized that in becoming an adult and family provider, my world-view shifted to a focus on survival and profit, which is far from the world-view of students.
I moved my blog from WordPress to Jekyll because I want to use the same publishing paradigms for both tech comm and the web. Jekyll also loads more quickly.
If you want to encourage engineers to write documentation, integrate your writing tools and process into their toolchain and workflow.
Peter Gruenbaum's API technical writing course on Udemy is an excellent starting point for learning API documentation. He explores one of the more difficult parts of API documentation, which is describing JSON and XML data structures (usually in responses).
