12) You should not type with your eyes closed.
-- OK. Fair enough. Nobody is saying that you should type with your eyes closed. However, there is no reason why you can't type with your eyes closed if you want to (providing that you know how to touch-type). If you've ever been inspired, or trying to transfer a perfect model of a concept held in your brain through your fingers and onto the screen, you'll know that everything else in the world is nothing but a distraction. ...and you'll realize that sometimes, the best thing...and perhaps the only thing that you can do to avoid losing the thought is to close your eyes and write. Of course, if you've never had this experience, there is no reason why you'd ever need to or want to close your eyes while typing...and even less likelihood that you'd understand what someone was doing if you saw them typing with their eyes closed.
11) Dense content is better because it is shorter.
-- If dense content increases complexity, cognitive load required to understand the topic, diminishes the accessibility of information within the content, and generally destroys any semblance of usability, then dense content is definitely NOT better. I've had more than one person (none of them writers) hold up the most compacted, impenetrable piece of gobbledygook to me as a model of how technical content should be written, and roll their eyes when the same content is revised for usability and understandability. In this context, the opposite of dense content would be content that has been revised by breaking information out into task, reference, and concept sections; content that has been reworked by chunking information, making use of parallel structure, increased whitespace, logical headings, etc... Such content often has a higher aggregate page count than the same information compacted into a block of text so tight that it is near impenetrable for the reader (and damn near impossible to maintain and change without springing the whole works).
10) Technical writing is easy. Just do it this way: _____________.
-- We've all been there. Schmitty's Law states that the less informed someone is on the theory or praxis of technical communication, the more amusing "their way" will be. The corollary to Schmitty's Law states that the more amusing "their way" is, the more vehemently they will argue for the immediate adoption of their approach and the less willing they will be to consider other approaches.
9) A low page count is more important than comprehensive content.
-- "Anything said in 40 pages would instead be better said in 10. (Regardless of the scope of material covered.) If it is not possible to decrease page count, consider changing font size, line spacing, and page margins to accommodate the requirement." If you've ever been the recipient of such myopic advice, you were probably damn near apoplectic thinking of how to even respond.
8) Users don't read documentation.
-- Even in the face of direct evidence to the contrary, people will still spout this adage and attempt to use it in order to justify doing "very bad things" to the resident technical writer, or asking him/her to do "very bad things" to the reader. An example of this would be, "Since users don't read documentation anyways, let's remove all task oriented procedures from the online help." Of course, the kernel of truth to this statement is that a) users quickly learn to avoid poorly written, dense, and inaccessible documentation and b) users do not read a user's guide, online help system, etc... cover to cover. They look for topics relevant to their current context.
7) You don't need to know when the software will be released in order to schedule your efforts.
-- Documentation should "just be ready" whenever the software is ready. This is sometimes called the jack-in-the box method of technical writing. That is, the tech writer cranks and cranks and cranks away on his/her projects and one day, SURPRISE! The software is posted to the web and we've released with nary a warning.
6) You don't need specifications to write software documentation.
-- Our software is so easy, you don't need specifications. In fact, users probably won't even need to read the documentation anyways...so you shouldn't need a specification to write it. This is a classic, and is usually the mantra of the engineers and experts who design the software in the first place. Needless to say, more often than not, the software is pretty darn complex when mere mortals are asked to use it.
5) You shouldn't use "you" in technical documentation.
-- Use of "you" is not formal enough for technical documentation. This seems to be a holdover from fifth-grade composition classes devoted to some ridiculous paradigm of "formal writing". Granted, there is no need to superfluously use "you" if a reference to the reader is not needed, but in some situations you can't avoid using it without sacrificing clarity and usability upon the alter of some misguided notion of formality.
4) The imperative voice is insulting to readers.
-- A task or procedure step should avoid being constructed in the imperative voice, "because it's insulting." I was told this by someone who then added, "I mean really, who are YOU to tell ME what to do!?!?" Uh, ok....
3) Users don't want to be told how to do anything. Instead, they just want the bare facts, and they will figure out everything else on their own.
-- Despite all the research to the contrary, this lovely gem comes up again and again. Reference material on window and system objects is all anyone needs to figure out everything they can do with the software. This bit of advice is often used in conjunction with numbers 4 and 2 in an attempt to advocate for number 11.
2) Everything can and should be reduced to a diagram with callouts.
-- There's no need for tasks/procedures. All a user needs is a screen-shot or diagram with callouts describing the main elements of the application/window/procedure/etc.... Everything else, the user can figure out on his/her own.
1) You are not allowed to cut and paste content.
-- Yes, I encountered this little bit of wisdom quite recently. I was even told I was "fooling readers" by making them read something twice, and that in general, "cut and paste is evil". That "cut and paste is evil" is, in fact, an adage that I agree with...when it comes to writing code. However, look at any number of competently written online help systems, user guides, etc... and you will see that content re-use is an essential element of technical communication. The idea that one cannot or should not cut and paste in technical documentation is about as ridiculous as it is misinformed. It's even more ridiculous when many a HATT has built-in support for managing content reuse.
Subscribe to:
Post Comments (Atom)
No comments:
Post a Comment