Why would you write topics instead of documents? It is easier to write topics than to write a document, kind of like walking a long distance is easier if you take it one step at a time. Topics are also easier for reviewers to review and for testers to test. Of all these easy-to-write topics, tasks are the easiest of all to write.
Topic-based authoring means you write topics, not documents. The topics are then assembled into print documents-manuals, guides-or online help. Topic-based authors describe topics by type: concept, task, and reference. You can create other less common types but I want to focus on these.
Task topics are easy to identify since they consist of just a task and nothing else. Task topics are easy to write for the same reason. It is easier to write tasks than any other type of technical writing, especially if you aren’t bogged down wondering what else you should include. The answer is nothing. This is an absolute. You write the topic title, then the steps, and include nothing else except maybe a ‘More information… ‘ link. Okay, occasionally you might include a Note or a Warning of some sort, but nothing else.
Concept and reference topic types are more difficult to quantify but just as easy to write. Generally, concept topics are descriptive of a general area of information, such as an introduction or theory of operation.
Reference topics, on the other hand, contain information that the reader might need to access to complete a task. Reference information could be a table of spark plugs by car type, a list of common symbols used on medical devices, or a pricing index. Information the user may need but that should not be in their face unless they want it specifically.
Rules and Guidelines of Topic-based Authoring
The first rule of topic-based authoring is to write all the tasks first. This was difficult for me-at first. I used to write from the top down and from the front to the back. It just felt logical. Sure, I encountered pitfalls with shoehorning missed or added information into already written chapters, but that was the way things were. Right?
Against my better judgment, and my twenty years of experience, I took the challenge and began writing tasks. Of course, this means that each task is in its own file, which felt very strange. However, the result was amazing. I could almost immediately see the benefit of writing just the tasks and writing each task as a single topic:
- I painlessly gained knowledge of the product by focusing on what each element of the product or application did.
- I was able to arrange and rearrange the topics as new knowledge came to me.
- I no longer had to shoehorn any information. When the project team came up with a new feature, I could write the tasks and shuffle them in where they belonged.
- I immediately saved on translation costs. Writing only the tasks, I realized many of the phrases were the same from task to task and started leveraging those phrases. After all, the more exact matches, the better.
- I could reduce redundancy in my writing. As I was writing the topics, anything that wasn’t a task went into a ‘later’ folder. When I pulled out that folder, I could clearly see which pieces were reference pieces so I started putting those together. I could easily weed out any redundancy that occurs when tasks have the same additional information.
After writing all the tasks, or all of the tasks you know about at the time, what do you do with all the pieces of information that are in the ‘later’ folder? These are pieces of information like why you pick this option over that option or what each option means.
When I finally wrote the reference topics, most of them ended up as tables or bulleted lists. When reviewing tasks, you can add cross-references to these topics, as needed. Or, if you are authoring in DITA, you can create a reltable in your ditamap. This is very cool and, if given the opportunity, you should try it.
Rarely do you need concept information for online help. Concept topics usually only come into play in print documents. If you are single-source authoring, you can rearrange and reuse these same topics you created for the online help for your print documents but you usually need to add those introductory pieces I mentioned earlier. See what I did here? I moved the discussion from topic-based authoring to single-source authoring. Actually, they go together.
For example, in a Users’ Guide, you could write a concept topic for the beginning of each chapter. When necessary, you could include a concept topic within the chapter for a section of like information. Because these are all individual topics, you can arrange them one way for one type of output-a manual or guide-then rearrange them with more or fewer topics for another type of output-online help or a Quick Reference document.
I got these results when I first used topic-based authoring:
- My word count went down.
- My exact matches for translation went up.
- Our online help usability scores went way, way up.
Some Tips and Tricks
Some habits we form when writing can haunt us and breaking those habits is hard. However, here are some things I learned:
- If writing from requirements documents, or getting your information from developers, make sure you are not providing more information than the end-user needs.
Some developers want all of their thought processes included and the user really, really does not care about what it took to get this control to work in this environment. Also avoid marketing messages. They already bought the device or application and really don’t want to be beat over the head with how great it is.
- End-users also do not want to read about a result that they can see happening.
For example, do not tell them that when they select Filter, the Filter window opens. If selecting a control launches a certain window, like a Filter window, they can see it. If you really must include confirmation of some sort, start the next task with, “On the Filter window,… ” That should tell them all they need to be sure they are in the right place.
- If you write a topic about a function that is performed in another window, you can usually do a cut and paste of some steps for that window. For example, if your topic is Filtering Controls, the first step is probably something like, “On the menu bar, select Filter.”
The filter window itself has a help button, of course, so copy all the steps from the “Filtering” topic except the first step. Copy and paste Steps 2 through N into your Filter dialog box topic and you have saved some work. Additionally, you now have steps that are an exact match for translation purposes.
In anticipation of your question, yes, if you are creating online help, you do need two separate topics, one for telling users how to access and use the Filter dialog box and the other for the Filter dialog itself. One is in the index under Controls, filtering while you map the other topic to the button on the Filter window. Think about it.
The real benefit of using the topic-based authoring is that you are able to leverage most online help topics for any print documents that are required. You get one topic, clear, concise for the reader and multiple outputs for the company. That means lots of bang for your buck.
Next time: Single-Source Authoring
