Author: Chris

Shubhro Saha on why software engineers should write

Software engineers should write because our craft is increasingly collaborative. Open source projects invite worldwide participation, while industry products often require an army of engineers. (Google Maps has 1100 full-time employees!) Good writing– whether it be in a GitHub comment, code review, or technical documentation– facilitates clear, concise communication for projects like these to move forward.

I’m going to take Shubhro’s essay on why software engineers (i.e. programmers, developers) should write one step further. Everyone should write about their craft. Database administrators, project managers, accountants, plumbers, Wal-Mart door greeter, you name it.

Writing is thinking. Writing helps you to understand your work better. To take a step back from the hustle and bustle and reflect on what you’re doing. You ask different questions about your craft when you take a moment to think and put it down in words for others to read.

O Human Star

After Nimona ended I’ve been looking for another interesting web comics series. I’m rather picky. The art has to be solid and consistent and the writing the same. I love sci-fi elements and anything that approaches the genre with a fresh voice. I think I’ve found my next obsession – O Human Star by Blue Delliquanti.

From the description on the recently successful Kickstarter,

Alastair Sterling was the inventor who sparked the robot revolution, and because of his sudden death he didn’t see any of it. That is, until he unexpectedly wakes up in a robot body that matches his old one exactly and finds out that 16 years have passed. Brendan Pinsky, Al’s former research partner and secret lover, now runs one of the largest robot manufacturers in the country. And Brendan’s dearest project, Sulla – a highly advanced robot with a mind copied from Al’s – is now living as a teenage girl.

Whaaaat? It’s as amazing as it sounds. Questions about gender, identity, mystery, what it means to be human – all great hooks for a story on their own – wrapped up into one beautifully written and illustrated story.

My only gripe is that I binged on every page and am now caught up. I have to wait to read the rest! Join me and be sure to start at the beginning!1

Tagging Semantic Articles Outside of the Factbox

One of my favorite Semantic MediaWiki features is the factbox. It’s a quick way to browse wiki content by property values.

What if you want a similar browsing interface within a wiki page? For example, let’s say you want a value for a property you use to ‘tag’ an article to provide a link to a list of all pages with that property/value pair. Here’s one way how. 2

For the past year one of the ways we’ve been using our wiki is to publish an internal monthly newsletter. Each newsletter article is a wiki page, with a template providing consistent navigation.

Screen Shot 2014-12-17 at 1.19.10 PM

 

Along the right hand column of every article are the tags for the audience and topic areas related to the article.

linked-list

Recently I made an addition to the list of Audience and Topic Area tags to provide dynamic links to all pages with that property value. I’m leveraging the SMW Special:SearchByPropertySpace special page.

In the article template, with the property “Facets Article Topic Areas” you’ll want to use an arraymaptemplate 3 to format the comma separated list of values. 4

'''Topic Areas''': {{#arraymaptemplate:{{{Facets Article Topic Areas|}}}|SearchByPropertySpace-FacetsArticleTopicAreas|,|, }}

What this will do is take every value for the property Facets Article Topic Areas and use the SearchByPropertySpace-FacetsArticleTopicAreas 5 template to format each value. Each value is separated by comma, and our final output will be separated by a comma and a space.

In the template “SearchByPropertySpace-FacetsTopicAreas” we have the following.

[[Special:SearchByProperty/Facets-20Article-20Topic-20Areas/{{#replace:{{{1}}}| |-20}}|{{{1}}}]]

This creates a link to Special:SearchByProperty where the property name is Facets Article Topic Areas and the value is each comma separated value from our arraymaptemplate.

The replace parser function converts values with spaces to URL encoded characters.

SearchByProperty

The result is that every topic area listed on the page becomes a link to Special:SearchByProperty that shows all pages with that value.

Screen Shot 2014-12-17 at 5.02.52 PM

When editors add a new article they only have to add a list of topic areas. 6 This makes in-article links to all other articles a click away without having to scroll to the bottom of the page to view the factbox.

Unreachable Time and a Rant Against Voicemail

I’ve been at my employer for over 3 years now.7 The entire time I’ve been here my voicemail message has said the following:

“Hello, you’ve reached Chris Koerner. I’m often away from my desk and don’t respond quickly to voice mail. The best way to contact me is to send me an email at me@work.net or if it’s urgent call me on my cell at 314-555-2456. Thanks!”

So, don’t leave me a VM, try my cell or email. I’ll answer my cell from a work-prefix number when I’m at work.8 I respond to email in a few hours at most.

My wife finds it amazing that I’m able to do this. That my boss doesn’t prevent this or that I haven’t gotten in trouble yet. Here’s my secret. I never asked my boss how I should make myself accessible and spend my attention. I decided that. He trusts me. I said, for me, the best way to get my attention is via email or cell call. Voicemail sucks.

Short of that. I’m unreachable. I think that’s important. Even with all the responsibilities I have and all the various ways to get in touch with me, sometimes I will not be available. I might be busy with a big project and a deadline. I might be in a meeting.9

I’m still accessible – even faster than voicemail! – and I’m polite about it. The important thing for me is making sure that the time I have allotted to get work done is as productive as possible. I use the tools I have – email, phone, IM – in the best way possible. To me, being accessible via voicemail is the same as being accessible via fax. Ancient, cumbersome, and a pain for all parties involved.

Voicemail is slow. Like most folks I read much faster that someone can talk. If I’m familiar with a topic I can quickly read an email and respond.

Voicemail also introduces ambiguity. Did they say ‘Six five seven two” or “Six five six two”? I’d have to play back the message if I missed a number, address, etc. 10

The tools we use should make us more productive and efficient. We should delight clients and co-workers with our responsiveness. Clunky, outmoded tools like voicemail don’t help us. I encourage you to look at how you’re using things like voicemail and see if there isn’t a better, more productive and friendly way to manage your attention and time.

Leave me a voicemail comment with your own ideas.