i suck at computers

26/12 Preventing Reader-Rage

I'm reading a book I intend to write a review for before the end of the month on this very weblog, but I needed to vent/discuss something in the meantime.

Unless you're telling a god damned story, don't use the first person.

Blargh! It is annoying whole new level to be reading a bit of quite technical writing spattered with phrases like: "[In the code above] Additionally, I implemented blah blah blah explicitly to give the compiler a ..." Or something a bit worse, first-person conclusions: "I quickly discussed method overloading in blah blah blah"

Albeit, I've not (yet) written a book, as a random dickbag on the internet it is my god-given right to call this author out for bad style, right? :) In quasi-technica writingl (i.e. the realm between developer documentation and a Clancy novel) I think addressing the reader is quite acceptable "if you use the -Wapocalypse flag, your brane will implode at compile time" but speaking in the first person is outright annoying. I cannot tell if this author is attempting to create some unnecessary connection with the reader of his book or what exactly he's attempting to do with the incessant use of first-person, but the consistency thereof has repulsed me enough to where I've skipped a number of paragraphs as soon as the author launches into a first-person, marginally-relevant, portion of text.

Just remember kids, even though your teachers might say of writing introductions and conclusions "tell them what you're going to tell them; tell them; then tell them what you've told them."

They don't mean it literally.

[tags: reader-rage, writing, first-person]

02/12 Zero Configuration Networking, The Definitive Guide

Zero Configuration, more commonly known as “Bonjour” (formerly known as Rendezvous) is a reasonably well known technology but a commonly misunderstood technology. Stuart Cheshire and Daniel H. Steinberg’s “The Definitive Guide” aims to walk a user from one end of the spectrum to another, starting with explaining what Bonjour is and isn’t, and ending with brief introductions to the C, Cocoa, Java, Ruby and Python APIs for including Bonjour functionality inside an application. In another fantastic “Definitive Guide” from O’Reilly, Cheshire and Steinberg not only explain how the technology works, but reasoning behind some of the design decisions, lessons learned from other technologies (AppleTalk primarily), and how Bonjour truly is one of the tools we didn’t even know was missing from the modern networking toolbox.

Stuart originally sent me the book after reading about some of my (primarily) experimental forays into using Bonjour for more than just iTunes sharing. While not too many developers, power-users, or even end-users are familiar with how Bonjour works, they no doubt have seen it in action, whether it be iChat Bonjour Messaging, iTunes Sharing, or the quick setup of their new network-capable printer. The book dives right into explaining what exactly Bonjour is, and the problem Bonjour intends to solve with a common problem even my grandmother can understand, if you set two laptops on a table, why can’t they communicate right off the bat with one another? From the end users perspective, they can “see” both of the computers, why can’t the computers “see” each other then? It is to this hypothetical naive individual this book seems to be written, as it is equally as frustrating for a software developer as it is for an end user to struggle with some of the issues the ever growing proliferation of networks has presented them. The duo [Cheshire & Steinberg] start to walk the reader through the dark ages, the forlorn days of “platinum” user interfaces, AppleTalk, and the venerable “Chooser.”

Read the full entry »