[mdlug] xargs guide

[Mike Mikowski]

On Aug 2, 2015 12:00 PM, Michael Corral <micorral at comcast.net> wrote:

> Even more off-putting than the excess verbosity were the many 
> references to "I" and "me" throughout the guide. Textbook authors tend 
> to avoid doing that for precisely that reason; only a few have ever 
> successfully pulled it off, and even then it can be polarizing (e.g. 
> D. Griffiths' physics books). To make matters worse, statements like 
> "That would be a firing offense at Troubleshooters.Com, where I control 
> everything," and "Because I'm a fairly smart person" make it seem 
> like the author needs to tone down the ego a notch or three. It's 
> especially silly in a simple guide such as this. 

I agree!

When we wrote Single Page Web Applications (http://manning.com/mikowski) we got an exemption from Manning's writing style to use the "we" voice, which was very well received.  In fact, they were considering revising their style guide because of this. In general, there are three voice styles you can choose from:

1. The "I" voice is often perceived as condescending and should be avoided.

2. The "you" voice can come across as accusatory.  It is often intermingled with the "I" voice and in such cases it tends to stroke the authors ego and seriously piss off the audience.  We had to review a book for publication by a young developer who constantly predicted what stupid things the user was guilty of, and how the author brilliantly avoided such stupidity.  The book isn't selling well. Go figure.

3. The "we" voice makes you a peer of the reader, and brings him along for the journey.  It is typically the least offensive form of writing, and can be a lot of fun for the reader.

IMO, the same rules apply for human interaction, although I often struggle to use voice 3 instead of 1 or 2.

Cheers, Mike