Monthly Archives: March 2013

Rewriting Programmer API Specs: Day I, Getting Oriented

Since most tech writers have to rewrite something a programmer wrote at least once in a while, and since this very task has afflicted me this week, I’ve decided to share some guidance on navigating this dirty deed. Here’s the high-level: Document:  The ABCCompany Offline Processing Specification General idea:  Our partners are companies who buy and then resell our data to their customers. To do this, they need to request and receive data from us (the ABCCompany) using a system-to-system interface. Document’s purpose: Explain to partners how to securely exchange XML batch files with ABCCompany. My mission: Turn prose that is both techy and schmoozy into clean, straightforward information. Day …

Continue reading

Posted in Uncategorized.

The Task Before Me: Rewriting Programmer API Specs

Occasionally, people at work figure out that tech writers write better than programmers do. They usually have this epiphany when (1) they’ve just finished slogging through a document written by a programmer, and (2) they notice a tech writer in their vicinity. At which point they reflexively ask the tech writer to “make the document more customer-friendly.” Which means, “Could you please rewrite this damned thing?” It was just such a series of events that drew me to the task at hand: Rewriting a suite of API specs to improve their clarity, organization, and layout. I’m flattered when my coworkers, who are familiar with my work, read something atrocious and …

Continue reading

Posted in Uncategorized.

The Hokey Yogi (Part 2): Do You Speak User?

Recently I wrote about how fitness instructors favor anatomical terms over more common words. I know this from personal experience. Not only have I taken lots of fitness classes, I’ve taught even more. When I got my fitness instructor certification and then my exercise science degree, I couldn’t wait to flaunt my credentials via my new vocabulary. I still shudder. But sometimes tech writers are no better. We stew in the language of product development all day long, we see it on the interface of the product we document, we read it in the specs about the product, we peruse the “literature” marketing conjures for the product…It’s no wonder so …

Continue reading

Posted in Uncategorized.