Writing a good technical documentation is hard. Most people don’t appreciate this fact. It is hard because we are emotional beings by nature and technical writing is…well…emotionless 
As a person from a Latin background, it is especially hard for me to avoid emotion in my writing. So after many years of hits and misses, I’ve compiled my own guide that helps me stay in check. It is not perfect but I believe it is a good start. Using it helped me to increase the number of hits while lowering the misses and at the end of the day that’s the goal: Not aiming for perfection, but continuous improvement
Interesting thing is, you can use this even when writing in social media. I am also someone who is slowing moving away from the operational IT tasks and more into the business and stakeholder dialogues. Understanding is paramount for this phase of my career.
Oh yeah, before I forget: I don’t care about these recommendations here in my blog. I want my blog to be organic and the closest as possible to the way I speak in real life. Cool?
Checklist for a Better Technical Writing
| # | Check for This… | If Yes, Do This… |
| 1 | Words “I” or “We” | Replace them. The document must be written in the 3rd person |
| 2 | Sentences are written in different verbal tenses | Make sure the whole document is written in past tense |
| 3 | A section called “abbreviation/nomenclature” section in your document | Make sure it towards the start of the document |
| 4 | Use of jargon. (eg.:“the system will go live on xyz”) | Avoid jargon with a clearer expression (“the system will be available for general use on xyz”) |
| 5 | Abbreviations in the “executive summary” or “abstract” sections | avoid them. Expand to their real meaning. |
| 6 | Usage of word “that” | All “that” has to be used when you know whom you are replacing |
| 7 | Usage of word “which” | All “which ” has to be used when you are unsure who is being replaced |
| 8 | Word “So” | Make sure “So” does not start sentences |
| 9 | Word “but” | Replace them with “however” |
| 10 | Word “To” | Make sure it is not at the start or end of a sentence |
| 11 | Words with “-ing” suffix | Make sure they are not starting sentences |
| 12 | Graphics, equations, tables in the document | Make sure they are addressed in a table of contents |
| 13 | Check for judmental constructions “It is very easy to perform the steps A, B, C” or “it is very difficul to determine the result of D, E, F” | Consider removing it or replace with cold, hard construction. What’s easy for you might not be for others and you are telling the readers are incompentent if it does not work. |
| 14 | Statistics and numbers | Make sure their sources are mentioned |
| 15 | Word “will” | Replace them with “may”. |
| 16 | Word “Obvious”, “Of course” | Remove them at once. If it is obvious, no need to state. You’re implying the reader is incompetent. |
| 17 | Sentences with exclamation marks | Remove them at once. |
| 18 | Words “can’t” and “won’t” | Replace them with “cannot” and “will not” |
| 19 | Expressions in parenthesis “()” | Consider replacing them with a comma |
| 20 | Numbers in sentences | Replace for their full wording: “it is 5 MB” should be “it is five megabytes” |
But I am Still an Techie at Heart
and considering that I still love to be a hands-on kind of guy. What you will see now is a series of scripts that can be used in your documents to automate the repetitive task of finding words and expressions that convey a colder and more understandable way to send a message. If you are a techie at heart like me, you will enjoy them
Bash is coming to Windows platform and now there is an expectation that people will quickly pick it up like they did with PowerShell. Once that happens and you also become a fan of Bash, use the following scripts for your work (from Matt):
Bash Script to Find Weasel Words
Weasel phrases or words are those that make you sound too good but does not really convey any meaningful information. Basically they make things unclear for the reader. For example: ”It is quite difficult to find untainted samples” when a better was is “It is difficult to find untainted samples”
#!/bin/bash
weasels="many|various|very|fairly|several|extremely\
|exceedingly|quite|remarkably|few|surprisingly\
|mostly|largely|huge|tiny|((are|is) a number)\
|excellent|interestingly|significantly\
|substantially|clearly|vast|relatively|completely"
wordfile=""
# Check for an alternate weasel file
if [ -f $HOME/etc/words/weasels ]; then
wordfile="$HOME/etc/words/weasels"
fi
if [ -f $WORDSDIR/weasels ]; then
wordfile="$WORDSDIR/weasels"
fi
if [ -f words/weasels ]; then
wordfile="words/weasels"
fi
if [ ! "$wordfile" = "" ]; then
weasels="xyzabc123";
for w in `cat $wordfile`; do
weasels="$weasels|$w"
done
fi
if [ "$1" = "" ]; then
echo "usage: `basename $0` ..."
exit
fi
egrep -i -n --color "\\b($weasels)\\b" $*
exit $?
Bash Script to Find Passive Voice Usage
Passive voice is a hard one. You can find it everywhere because it is related to the way we think and process sentences. When people advise to read and re-read the text before publishing it, it is because we want to pickup the passive voice. Passive voice usage is bad because often it hides explanatory information, for example: “Termination is guaranteed on any input” instead of “Termination is guaranteed on any input by a finite state-space”
#!/bin/bash irregulars="awoken|\ been|born|beat|\ become|begun|bent|\ beset|bet|bid|\ bidden|bound|bitten|\ bled|blown|broken|\ bred|brought|broadcast|\ built|burnt|burst|\ bought|cast|caught|\ chosen|clung|come|\ cost|crept|cut|\ dealt|dug|dived|\ done|drawn|dreamt|\ driven|drunk|eaten|fallen|\ fed|felt|fought|found|\ fit|fled|flung|flown|\ forbidden|forgotten|\ foregone|forgiven|\ forsaken|frozen|\ gotten|given|gone|\ ground|grown|hung|\ heard|hidden|hit|\ held|hurt|kept|knelt|\ knit|known|laid|led|\ leapt|learnt|left|\ lent|let|lain|lighted|\ lost|made|meant|met|\ misspelt|mistaken|mown|\ overcome|overdone|overtaken|\ overthrown|paid|pled|proven|\ put|quit|read|rid|ridden|\ rung|risen|run|sawn|said|\ seen|sought|sold|sent|\ set|sewn|shaken|shaven|\ shorn|shed|shone|shod|\ shot|shown|shrunk|shut|\ sung|sunk|sat|slept|\ slain|slid|slung|slit|\ smitten|sown|spoken|sped|\ spent|spilt|spun|spit|\ split|spread|sprung|stood|\ stolen|stuck|stung|stunk|\ stridden|struck|strung|\ striven|sworn|swept|\ swollen|swum|swung|taken|\ taught|torn|told|thought|\ thrived|thrown|thrust|\ trodden|understood|upheld|\ upset|woken|worn|woven|\ wed|wept|wound|won|\ withheld|withstood|wrung|\ written" if [ "$1" = "" ]; then echo "usage: `basename $0`..." exit fi egrep -n -i --color \ "\\b(am|are|were|being|is|been|was|be)\ \\b[ ]*(\w+ed|($irregulars))\\b" $* exit $?
Perl Script to Find Lexical Illusions
A lexical illusion is another form of visual illusion, normally happening when a like break contains repeated words but due to the way we read things, it is not easily spotted. Microsoft Word has actually a very good Lexical Illusion detection feature but still a lot of those can be left in place.
#!/usr/bin/env perl
# Finds duplicate adjacent words.
use strict ;
my $DupCount = 0 ;
if (!@ARGV) {
print "usage: dups ...\n" ;
exit ;
}
while (1) {
my $FileName = shift @ARGV ;
# Exit code = number of duplicates found.
exit $DupCount if (!$FileName) ;
open FILE, $FileName or die $!;
my $LastWord = "" ;
my $LineNum = 0 ;
while () {
chomp ;
$LineNum ++ ;
my @words = split (/(\W+)/) ;
foreach my $word (@words) {
# Skip spaces:
next if $word =~ /^\s*$/ ;
# Skip punctuation:
if ($word =~ /^\W+$/) {
$LastWord = "" ;
next ;
}
# Found a dup?
if (lc($word) eq lc($LastWord)) {
print "$FileName:$LineNum $word\n" ;
$DupCount ++ ;
} # Thanks to Sean Cronin for tip on case.
# Mark this as the last word:
$LastWord = $word ;
}
}
close FILE ;
}
For more tips, you can have a look at http://matt.might.net/articles/shell-scripts-for-passive-voice-weasel-words-duplicates/
So there you go. These are my tips. Share yours in the comments and I will include them here and credit it to you.
No comments:
Post a Comment