![[spacer]](1p.gif){kind=small} |
| ||||
|
Conditions Are Your Friends |
When writing single-source documents, try to keep all the different output uses in mind during composition. This isn’t always easy, but it offers rich rewards. For example, suppose you are writing a description of a software procedure for both printed manuals and WinHelp. The reader of the printed manual may want to know the reasons for certain steps in more detail than the online user, who is in the middle of the task. So put the essentials first, then elaborate; you can apply a PrintOnly condition to the details so that they don’t clutter up the WinHelp. The same thing applies to the graphics. For the print copy, you may want screen shots so that the reader who is away from a computer sees what you are talking about. For online use, screen shots often just get in the way and confuse the user, who tries to push buttons on the screen shot instead of on the real dialog and gets frustrated when nothing happens. Instead, you may want a graphic with just the bit of the dialog you are discussing, or no graphic at all. As you can see, single sourcing does not mean that you use the same content for all purposes. That would usually be wrong; it is in fact the major criticism levelled against single sourcing by those who do not understand what it really is. You may start out that way, by writing for the print docs first, and then revising for the online help. And if you run short on time, it’s tempting to use the print-doc text as-is. Try not to succumb to this. At the very least, put the more theoretical parts of the text at the end of their chunk, and make that part its own topic that online users can skip over. (In Mif2Go, you can use WinHelp "sliding topics" or HTML "extracts" to automate this separation.) Choose your condition names wisely. In FrameMaker, you can select several conditions at once to show or hide, but this may not work as you hope. Suppose you use condition tags named "PrintOnly" and "HelpOnly"; when you tell FrameMaker to show PrintOnly and hide HelpOnly, you get the results you expect. Now, suppose your doc has variants for different product models, so that you also have "TypeA" and "TypeB" tags. Naturally, there’s overlap in the tagging, which is fine. But when you say to show TypeA and PrintOnly, and hide TypeB and HelpOnly, what happens? You get all the PrintOnly text... including that for TypeB. Why? Because if you show any of the conditions with which a piece of text is tagged, that text is shown. In formal logical terms, FrameMaker gives you the "OR" of all the conditions selected for showing; it cannot give you the logical "AND", or even a logical "NOT". So you have to design your tags with that limitation in mind. In this case, you need TypeAPrint, TypeAHelp, TypeABoth, and the same three for TypeB. It’s not pretty, but it works. Another conditional text limitation has to do with tables. You can give a table row a condition, but you cannot give a table column one. If you try to give the text in the column cells a condition that you then hide, you will see an empty column there. There’s no good answer; often all you can do is make alternate versions of the entire table. You may be able to make the unwanted column disappear by redefining its width to near zero in the table format in a template, and then applying that template during conversion (another Mif2Go specialty), but this only works if it’s the same column every time you use that table format. | ||||
|
|||||
