DocTrain East Day One

Following the tradition of previous DocTrain conferences, this one started off with a set of day-long pre-conference workshops. For a variety of reasons, I decided to take in the two sessions on topic-based authoring using MadCap Flare. Led my Mike Hamilton (MadCap’s VP of Product Management), the sessions opened my eyes to Flare’s capabilities and did a bit to change my opinion of the tool.

Not that I was anti-Flare or anything like that, but my brief flirtations with Flare left me thinking that it was a complex tool that would take a while to master. I still think that, but now I have an idea of what Flare can do and (to a degree) how to make it do the things that I want it to do.

The first session was notable because Hamilton gave some of the best explanations of XML, single sourcing, and multi-channel publishing that I’ve heard in a long time. You can see those explanations in the session slides that Mike Hamilton will be posting to his blog.

The morning session was an introduction to topic-based authoring with Flare, while the afternoon session focused on content control and publishing techniques. Hamilton took the participants fairly deeply into the application, and demonstrated how to use Flare to create content, and to import from Word and FrameMaker.

Hamilton also gave the group a quick run through of Flare’s upcoming DITA project import feature. At a high level, this feature can pull in a DITA topic map and enables you to map styles to the DITA files on import.

So, what did I get out of the session? A few things:

  • Mike Hamilton stressed that when using Flare, you need to forget about how you worked with other tools. You don’t use Flare in the same way that you’d use, say, FrameMaker or Word.
  • Planning a project is one of the keys to success when using Flare. Understand that needs, the scope, and the deliverables before even starting Flare. This seems like tech writing 101 but that’s something that some users of Flare seem to forget.
  • Think in terms of topics. Hamilton suggested that you create what he calls a cloud of topics, and from there pull those topics together into your deliverables. Keep things based on tasks — identify the tasks, and then fold in the concepts (which explain why) and the reference material (which contain any additional information) into the tasks.

Overall, my impression was that the key to success in using Flare is preparation. Once you’re prepared, and once you know the application, creating content becomes smoother.

Tips on designing training materials

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?

Weekly links roundup

A thousand words, or a waste of space?

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.