Sometimes, I hate Tom Johnson. OK, not really. Tom’s a great guy, and you can’t help but like him. But sometimes he beats me to something that I had planned to do. This time, it was interviewing Scott Abel. In this interview, you get some insights into organizing conferences, and what conference attendees should have in mind before deciding to go.
Some of the folks in our wacky profession don’t just create documentation. They also create learning materials — courseware, tutorials, and the like. Having done a bit of that in the past, I can tell you that it’s not as easy as it seems.
As with documentation (or any other kind of writing, or anything else for that matter), one of the keys to a successful training project is a solid plan. A design, if you will. This article discusses how to successfully design learning. While it’s written from the perspective of a technology professional who’s designing his or her own course of study, you can apply the advice in the article to the process of creating training material.
The key points are:
- Create a plan
- What do you need to learn?
- How are you going to learn it?
- How will you know when you’re done?
- Here’s a good usability tip: use verbs as labels on buttons
- Interested in designing (or even writing) for mobile devices? Then check out this article
- Anne Gentle looks at outputting DITA to WikiText. We saw a demo of this at DocTrain West 2008, and it was pretty cool
- Have a lot of conditions in your FrameMaker documents? Then take a peek at this article, which looks at automating them
- Overview information can be a chore to write. Craig Haiss offers some good advice on how to write informative overviews
A picture is worth a thousand words. I wish that I had $20 for every time I’ve heard that hackneyed phrase. Or even $10. I probably wouldn’t be rich, but I’m sure that I could pay off a chunk of my mortgage …
Seriously, though, there seem to be a number of technical communicators who take that phrase seriously. They create documentation that’s packed with screen captures, diagrams, flowcharts, and more. In most cases, the images don’t do much for the document except take up space.
Images included in documentation need to be more than just mere eye candy. The should illustrate something that’s difficult to describe using only words. Images enhance the text; they don’t replace it. To be honest, most images that I’ve seen in many of the user guides that I’ve read have done nothing to enhance the text I was reading. They just mirrored what I was looking at. Digital repetition at its finest.
I’ve heard some technical communicators argue that including screen captures is important because they “let the user see what’s happening in the application.” Yes, I’ve heard that sentiment more than twice. What we fail to realize is that someone will be probably be using the documentation while in front of an application or gadget. Unless they’re trying to familiarize themselves with a product, they won’t read the docs while riding the bus home or just after dinner.
That said, images aren’t always unwelcome. As I mentioned a couple of paragraphs ago, a well-chosen image is useful. But the key words here are well chosen. Just capturing every screen you can and sandwiching it between blocks of text just doesn’t work. Like anything else in your document, images should have a purpose. If they don’t strip them out.
How do you use images and screen captures in a document? Feel free to leave a comment.
Susan Wu (who blogs at Shanghai Tech Writer) has just finished her first year as a technical writer at National Instruments in (surprise, surprise!) Shanghai. She writes a retrospective of that year here. From the looks of it, that year was packed with a lot of learning — not just learning related to mere technical writing, either. What’s evident from this post (and I’m not just talking about the last paragraph, either) is that Susan enjoys what she’s doing.
It’s been … well, quite a few years since my first one on the job. Looking back, I (vaguely) remember some of that early joy along with a few frustrations that helped me grow professionally.
So, here’s a question I’m throwing out to the fives of people who read this blog. What do you remember (good and bad) about your first year as a technical communicator? Leave a comment, and the best ones will be collected into a post sometime in the near couple of weeks.