by

How to Write a Better Technical Document…and Use Windows Bash with it

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 Smile The less emotion, the better.

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 Smile It can be quickly summarized in the following graphic:

image

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? Winking smile

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 Smile That are done in Bash.

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.

image

#!/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.