Re: FONT STANDARDS
Isaac Rabinovitch wrote:
There really needs to be some careful thinking done here, and no just
in the font. I wish writers and editors would invent concise ways of
conveying this stuff. I hate reading "Choose X in the Y menu, then
choose Z". It's hard to follow.
Could you perhaps expand on that comment? I'm interested,
but not at all sure I understand what you're getting at.
Reasonable question. OK, suppose you're writing about Microsoft Word options. So you write about creating a backup copy. You write "From the 'Tools' menu, choose "Options". This brings up the options dialog box. Click on the 'Save' tab, and make sure that 'Always Create Backup Copy' is selected."
Then you have to write about embedding fonts. You write ""From the 'Tools' menu, choose "Options". This brings up the options dialog box. Click on the 'Save' tab, and make sure that ..."
After you've done this 3 or 4 times, your reader is screaming, "I get it, I GET IT. You want me to bring up the options dialog and click on the 'Save' tab!"
Or suppose you're just running through all the Table commands. "To insert a row choose 'Row' in the 'Insert' menu in the 'Table' menu. To delete a row choose 'Row' in the 'Delete' menu in the 'Table' menu. To select a row...."
Eyughh!
There are several things going wrong here. First, you're using tangled language. That's not fair to a reader who's struggling to understand some complex techical concept, and maybe doesn't have the extra mental energy to untangle nested subordinate clauses. If you're going to write about a bunch of menu items, you need to invent a simple convention for them (like "Tools/Options/Save" maybe with special icons to indicate menus, menu items, and dialog tabs) and stick to it.
Then there's the business of explaining the same thing over and over. Sometimes you can't avoid it -- like if you're trying to keep your help topics free of unnecessary hyperlinks. But suppose you're writing in a narrative style. Like you're writing one of those thick books that describes every single feature of an application. If you keep explaining the same stuff over and over, you're making it hard to read, and you're making the publisher pay for lots of pages that aren't necessary. So you don't give a complete explanation of a dialog every time you refer to it. You say, "Here's the dialog. Now here's what you can do with it..."
Finally, there's the conceptual framework of your document. If you don't think about this, you end up writing a bunch of specific little procedures that lead the user by the hand, without giving them any notion of what the pieces are and how they fit together. Some writers seem to think that's the best way to explain things. And maybe it is -- if all your readers are technophobes who just want you to answer a lot of "how do I..." questions. But writing that kind of prose is like bailing out a boat with a spoon -- you can never really catch up with the user's needs, because they will always have new ones.
I much prefer to help users build the conceptual framework they need to solve their own problems. More challenging me, and (for the kind of users I write for), more useful.
References:
FONT STANDARDS: From: Anna Langley
Previous by Author:
Re: Where does Documentation belong?
Next by Author:
It's what It's
Previous by Thread:
Re: FONT STANDARDS
Next by Thread:
Re: FONT STANDARDS
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads