In a recent issue of the New Yorker, Atul Gawande argues quite persuasively that like participants in sports, surgeons (like himself) can benefit from coaches. Even the elite stars, like Rafael Nadal, he points out, have coaches, observing, watching every move of the tennis great. Why, he wonders, don’t doctors – even senior, experienced ones – have coaches? As he says, “”I’d paid to have a kid just out of college look at my [tennis] serve. So why did I find it inconceivable to pay someone to come into my operating room and coach me on my surgical technique?”
When you are a company dealing with your customers’ most valuable personal information, you need them to trust you. One easy way to do this is to have your documentation flawless (or close to it). Also, performing a test run with a small group of people before releasing it to the masses is a good idea. The group of people should be 3rd party users who can find the mistakes you can’t find (since you’ve read and reread the form 40 times and never want to see it again).
As “Intern Emily,” I may be a bit biased, but I think that everyone should be using interns. Among the plethora of reasons, here are a few I see:
Through great marketing and market saturation, Microsoft Word has become the de facto tool for documentation. This should come as no surprise since Word is the most popular word processing tool—in fact, the “most popular software in the world for personal use” as MS Office Live Director of Marketing Michael Schulz said. Naturally, when people chose a tool to create documentation, they used what they knew: Word. The question is, is it always a good choice? The answer is a resounding no.
The topic of my Management Information Systems class this morning was the use of information technology in education. My professor, a critic of the traditional education model, drew this disturbing comparison: how business is done versus how education is done. I was shocked. “But business is USING information, and education is GETTING information!” I thought.
There is an unfortunate trend towards using more images and icons and using fewer written instructions (I like to say “words”). Personally, I don’t think it’s obvious what every icon actually is and what it means, especially when I’m in a hurry to do something.
Technical writing is all around you, but do you really know what it is? The goal of technical writing is simply to communicate information about technology that the reader can use and understand. That’s easy, right? There are three main types of technical writing used to accomplish this goal: end-user documentation, hardware and software technical documentation, and technical marketing communications.
Hello again readers! Last time we “met,” I had the pleasure of walking you through a quick primer on the Kirkpatrick model and how to best use it to assess the effectiveness of a given training program or set of training materials. My main argument was – whatever you do – make sure to focus on metrics that allow you to show measurable positive impacts that can be easily translated into $ savings. The bottom line is… well, that’s what your manager will be looking at, the bottom line. What’s the return on this documentation investment? At the end of the day, how many dollars does it put back in our pocket?
Trove ran a survey on Hacker News recently asking developers about their biggest pain points for API integration. While OAuth and backwards incompatible changes got their fair share of vitriol, I bet you can guess what the top source of frustration was.
Documentation.
Head over to the survey results, and scroll down to question 6 to see what developers hate about your API. Then ask yourself if maybe your API documentation needs a little help.
Whenever I go through a Word document with clients and they ask where a section is, I always refer them to the Document Map. Frequently, they don’t know what it is. Do you know what it is?
In short, Document Map displays the table of contents on the left side of your screen. This is helpful when searching for sections in a document even if there is a table of contents (less back and forth). You just have to make sure your text has heading styles applied to it correctly.
To find it and use it, follow the steps below.
