If you’re starting out in technical writing, here are some things to consider when adding screen-caps to user manuals and training guides.
Next time you’re testing your UI, think of this.
(Editor’s Note: This is the blog post I gifted as a secret santa blog. I have republished it here, with a few small embelishments.)
I had the great fortune to attend the Cognitive Colloquium in early October of this year at the IBM Watson Research Center in Yorktown Heights, NY. It was one of those life-changing moments when you feel like you’re sitting on top of a mountain and you can see much more distant horizons. In my case, the horizon I saw involved using some of my mental energy to solve the grand problems of digital content using the methods of cognitive computing.
What are these methods? Well, at IBM, we describe cognitive computing as a cluster of practices that use machine learning, natural language processing and high-performance computing to change the way computers work and how humans work with them. Heady stuff, I know.
View original post 1,860 more words
When a new designer joins an existing project, the temptation to show the designer the interface rather than the spec is hard to resist, especially if the two are not very similar. The problem is that some information that was in the spec is very important to the designer, but will often not be communicated in an interface review.
So here are some things you need to remember to tell your designer if you’ve spared them the need to read your spec.
All testers know the feeling: coming in on a Monday, looking at your notes from last week, and understanding nothing. If not for the handwriting, you’d think they were someone else’s notes.
How do you write notes that you’ll understand on a Monday, without wasting too much time? Here are some tips, in no particular order:
Capitalization seems to be a weak point for many in software. Perhaps because code (and odd company names) teach us that words can have a capital letter in the middle, capitalization of UI text is often more creative than is strictly necessary.
Capital letters aren’t important only because some of your users are grammar geeks; they’re important because they’re nice visual clues. They show clearly where a sentence starts, the difference between title and sentence, what’s a name and what’s a verb. But most importantly there are some – perhaps your potential funders – who will assume, if you avoid capital letters, that you simply didn’t learn how to use them.
Now, the truth is that capitalization is a delicate business. If you want to really get into it, which I encourage, find your style guide and get going. I assume, however, that you’re not that interested. This will do for most UI decisions.
Teresa Torres has an interesting article about finding common ground with engineers during feature discussions. Nice tips for the next meeting.
And over at Feld, a discussion of UX and ownership. If you’re a tester, you’ve run into this difficulty yourself – a UX that falls apart and has no mommy and daddy to put it back together.
A helpful UI is not as rare as a friendly one, because being helpful is more of a technical skill than a personality. Helpful means informative and organized, as well as comfortable to use. I’ll discuss organized and comfortable in a later article. For now, let’s talk about informative.
When explaining complicated ideas, your goal shouldn’t be to dumb things down – you’re here to teach, not to help people avoid learning. But the best way to teach is not to start at the expert level and hope your readers follow along – it’s to start at the bottom and layer it up. Give people a tiny amount of information, then a tiny amount that builds on that, and then a little more and a little more.
As an engineer you probably know this, but because you’re a field-expert, not a writer or a beginner, you may not build your layers correctly. Primarily, I suspect your definitions of “common knowledge”, “tiny amount of information” and “gaps that can be filled by the reader” are too broad.
Luckily, constructing layers is not an art-form; it’s a simple technique, and you don’t have to be a writer to do it correctly. So here’s the recipe.
Because I am both a technical writer and a software tester, one of my pet peeves is an interface that falls apart when it needs to communicate anything to the user. On every project I see code instead of text, poor grammar and spelling, ALL CAPS, odd choices of punctuation marks and a great many other sins against language. But the most basic mistake is simply not to understand that it’s okay to talk to the users in clear, simple language.
One of the challenges of project work is that you have to get into things quickly and without much help – in many places, people will have neither the time nor the inclination to teach you.
Remember that if you want to write about how something works, you have to understand the why of it as well. Users have to be given a context in which to work, a logical explanation to why things have to be done a certain way. It makes it easier for them to remember, and it removes the frustration users experience when they think an application is making them work hard for no real reason. So it’s not enough just to figure out the UI to stay one step ahead of the user – you have to really understand what’s happening.