Saturday, 27 June 2015

technical - What voice should I use when explaining how to program a computer?

I'm planning on writing a blog about computer programming, and I'm having trouble finding the right voice. I'm looking for something that feels personal and conversational. Third person seems sterile, first person singular comes across egotistical, second person comes across as bossy.



I've been using second person plural, which has an inclusive feel to it, but that takes away from the conversational feel of the non-technical parts of the piece.



Here's a quick example:



Let's say that we have a pipe delimited text file called 'addresses.txt' where
the first line of the file is a header with column labels:

First Name | Last Name | Street Address | City | State | Zip |
Homer | Simpson | 742 Evergreen Terrace | Springfield | OR | 97477 |
Marge | Simpson | 1094 Evergreen Terrace | Springfield | MO | 65802 |
Bart | Simpson | 1092 Evergreen Terrace | Springfield | IL | 62704 |
Lisa | Simpson | 59 Evergreen Terrace | Springfield | ME | 04487 |
Maggie | Simpson | 94 Evergreen Terrace | Springfield | WI | 53176 |

We can use a for loop to pull and print each field of the header

for i in {1..6};
do
header="$( head -1 addresses.txt | cut -d '|' -f $i )"
printf "%d: %sn" $i "$header"
done


This works when I'm describing how I want the reader to write a piece of code, but it doesn't work when I'm describing the programming language as a whole:



The Bourne shell is a full fledged programming language, complete with
branching and looping constructs. These constructs can be used on the
command line, affording us a great deal of expressive power without a
lot of typing.


This comes across as dry, and the token 'affording us' is weak. Furthermore, writing the whole blog in the first person plural seems artificial.



How should I approach this?

No comments:

Post a Comment