by

I’ll be at the GovHack Australia 2016!

I am humbled, honoured and excited to be part of the GovHack Australia 2016. I will be there as a Team Leader helping with the idea and concepts of the solution. If you never heard about this event, let me explain a bit more about what it is.

image

What is GovHack?

GovHack is an event that build teams to create innovative solutions using Open Government Data. Teams are formed with project managers, entrepreneurs, developers, designers, researchers, open data enthusiasts etc. Even story tellers are in there Smile Have a look at the report from last year’s event here.

 

What is a Hack?

A hack is to take something and make it better.  Our teams will look at the available data exposed by open government data sources and make a cool, useful and engaging application.

 

How Does it Work?

On the Friday night launch the competition categories are announced, the teams are formed and the event runs for the next 46 hours. The teams will then look at the datasets and create things with them. The best applications are in for prizes in International, National and Local categories. At the end of the GovHack a proof-of-concept and a video are created explaining the solution. Teams work through the weekend and by Sunday 5pm a 3 minute video of your concept and any code/source materials must be made public.

 

When is GovHack Happening?

In 2016, GovHack will happen from 29th to 31st July. Yep, the Prime-Minister supports it Smile

 

Who is Behind the GovHack?

This is a non-profit event proudly run by volunteers who form the GovHack Coordination Team. Our ongoing thanks to everyone who gets involved and makes GovHack awesome! That is, the hackers, data providers, sponsors, mentors and a special thanks to the volunteers who run Local GovHack events.

 

 

Who is Sponsoring GovHack Australia 2016?

Several big IT companies and Fare behind this effort such as:

image

image

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.