CodeSmells indicate deeper problems in code.
TextSmells indicate deeper problems in text, such as emails or Wiki content.
The goal here isn't really to list air fresheners, since they only mask the smell (though they help in a pinch). The goal is to determine the source of the smell and remove that. Often, in writing, this source of problems stems from the thoughts behind the words. Oh, that we could improve those thoughts.
Rebellion against these can sometimes help you communicate better, add flavor, or just reduce the amount of time it takes to write. It can be paralytic to obsess over the details as you write, just as in programming. A good strategy might be to get a first draft going that's as smelly as it wants to be and return afterward to revise.
Smells that Distract the Reader:
- Footnotes
- (See: FootnotesDestroyFlow) Footnotes are parentheses times two. If the footnote is large enough, maybe it belongs in a separate document entirely? This is more true when communicating via electronic media, because jumping around the screen is a pain.
- Excessive Humor
- If there's a joke in every paragraph, the reader may be amused, but miss the point. The reader who just wants some answers may find the humor aggravating, especially if the jokes are predictable. Remember, when you're writing, you can't see your reader's faces to know whether they're laughing, so don't assume that they are.
- Too Wide a Vocabulary
- Keep your audience's vocabulary subset in mind. Try to avoid using a bigger word when it's bigger but no more accurate than a simpler alternative. Eschew obfuscation.
- Too Narrow a Vocabulary
- Excessive redundancy in your word choices can be just as confusing as excessive variety.
- Relying on Previously Known Information
- Test your assumptions -- try to read your documents as though you didn't write them. As a bonus, this technique can help you catch other errors such as typos. Unfortunately, this is extraordinarily difficult to do. Some techniques to make this easier are: practice, leaving the text and coming back to it, and RubberDucking.
- Failure to Rely on Previously Known Information
- A sure-fire way to get your reader in "skim-mode" is to tell them things they already know.
- Mixed Metaphors
- The text "smells" are "traps" that cause "red flags to be raised", are they?
- Complex Constructs
- Double-negatives, (...what else?)
Smells of Superfluous Protocol
- AnneShirleyApologys
- Consider the likely effect of what you are saying. Don't write, "I'm sorry, but" because it will have the opposite effect to an apology. Instead, write things that you don't have to apologize for.
- Noisy Announcements
- As said in TheElementsOfStyle, "Instead of announcing that what you are about to tell is interesting, make it so." The same goes for announcing humor, quality, insightfulness, truthfulness, and so on.
Smells of Suboptimal Wordings
- Parentheses
- Causes the reader to nest their thoughts too much. Do you really need to include that parenthetical comment? If so, maybe it deserves to be a sentence of its own. If you can't make it a sentence right where it is, perhaps it should be a small paragraph?
- Not Being ShortAndToThePoint
- Ask yourself, "Why am I leaving that paragraph/line/word in?" Is it because it serves a purpose, or because you spent all that time creating it? KillYourDarlings. OmitNeedlessWords and read TheElementsOfStyle.
- Formatting (italics, bold face, etc.)
- I challenge you to GIVE me an example where you _can't_ live *without* this kind of >>MESS<<. Having to think about a way to emphasize certain words without funny characters can help.
- Emoticons (=), =P, ;))
- We all love them, but it's easy to fall into the trap of using them instead of more expressive and clever means of conveying the same thing. It's also easy to use them to avoid saying anything at all. See EmotionOnWiki.
- Run-ons
- The sure mark of a "first-draft" sentence, but at least they are somewhat easy to fix. Not necessarily a smell if the sentence is long, but still has a necessary structure and articulation. The rule of thumb is to try breaking it up, and see whether that works as well.
- Large Paragraphs
- Can the thought be broken up into more distinct ideas? This is especially useful for emails, as it makes it easier to naturally interleave replies with the original text.
- The "-ing" Suffix
- Compare these two sentences: "Resorting to adding '-ing' to words can lead to confusing constructs." "The '-ing' suffix tends to complicate sentences."
Smells of Ambiguity
- Too many pronouns, especially the word "Thing"
- Pronouns force your readers to retain context. Too many pronouns, and your writing becomes ambiguous.
- Passive Voice
- Compare "The ball was kicked by the boy" to "The boy kicked the ball". Passive voice focuses on the effect rather than the cause, which is why it's a stylistic tic common to people who have no vested interest in understanding why things happen and how to change them, such as politicians and bureaucrats. Don't be a bureaucrat.
- No Passive Voice
- Compare "The car was totalled" (passive) with "I totalled the car" (active). Different implications, which is why we have the two options.
I disagree with the usage of synonyms. Don't use them as a decoration but rather to shift the focus a little bit to a different aspect of the subject.
I highly recommend Joseph William's Book "Style Toward Clarity and Grace" ISBN 0226899152 . It addresses especially the coherence of a text and debunks some of the "rules" taught at school. -- Christian Lindig
A helpful technique to discover these patterns is to look through your "Sent Mail" folder. Look at the mails you did like, as well as the ones you didn't. Is there a theme?
Would this be a text smell -- having a summary list of items (say 20), followed by each point being discussed, which when counted reveals 28 items. A very big smell of something having gone very wrong.
cf. EightSystemMetaphors
Curiosity point..Is it possible to write scientific papers that are easier to understand? I have but one degree, but I do make an effort to read conference proceedings and can generally parse out the content in my head, but it takes time. Is it that learned CS professors just don't know how to write in a way that people can understand easily, the sort of topics that papers are written about just don't lend themselves to easy understanding, or is it that nobody would publish a paper that didn't look like your traditional hard-to-parse paper?
I've had people much more learned than I suggest that the third one was the reasoning. ;)
-- KenWronkiewicz
It's probably a combination of all three. In regards to the first one, it's not a failing solely of CS professors. Writing effectively is a skill, just like anything else, and a lot of people simply never learn to how do it.
On further reflection, I'm not sure that what we have here are TextSmells. They may simply be problems with the text itself.
In the case of CodeSmells, the smells aren't things in the code that need to be fixed. They're signs that something needs to be fixed. You don't fix the CodeSmell; you use the CodeSmell to lead you to the thing that needs to be fixed.
Implicit in the idea is the notion that whatever you're working on -- code, text, buildings -- has a bit of a life of its own, and wants to conform to a certain type of form. If there's a mismatch between the form that the work wants, and the form you're trying to fit it into, a smell will result.
Most of these TextSmells aren't really like that, are they? They're definitely useful rules-of-thumb. But they seem far too direct to be called "smells".
I can't think of many decent TextSmells of the kind of thinking of, but perhaps as an example:
- Conversation stops suddenly. Sometimes conversation on a Wiki pages dies off suddenly. There are loose threads and unanswered questions everywhere, but weeks and months go by and nobody contributes. Usually, that's because the form of the existing is so malformed as to repel further conversation. Maybe it's disorganized. Maybe it's extremely combative. Maybe it's just too long for people to edit. Time to refactor.
-- francis
Francis, after thinking about his off and on for several months, I'm probably going to agree. This page needs to return to its roots. I have two main goals for the new refactoring:
- As you mentioned, everything on this page should be a "smell" in that it should be an indicator rather than a problem, itself.
- Everything on this page should be talking about smells in the text.
In keeping with goal #1, I nixed a bunch of items from this page. They were all either: a) something I added, or b) referenced elsewhere on the Wiki, so I have a good amount of confidence in these changes.
In keeping with goal #2, the "IdeaSmells" up at the top moved to their own page.
More refactorings to come, most likely.
The word "usage" is, itself, misused quite a bit. There's a book: "On Writing Well". Note that "usage" can be the amount or manner of use.
Don't forget GeorgeOrwell's PoliticsAndTheEnglishLanguage.
See: ConversationalChaff
CategoryCommunication
BiLinks:
<-> http://www.usemod.com/cgi-bin/mb.pl?AbbreviationsAreEvil depends on the context
Text Smell