On Publishing and Writing and Documenting

Reading

I was telling my daughter the other evening that it is important to know how to spell, and just as important to know how to write (and write well). She’s going into 5th grade, so such a lecture may be a bit premature. No worries. This lecture will be a repetitive one.

As I recall, the conversation came up when I made note of how impressed I was that she was reading a book just for fun on summer break. Reading–reading real books by real authors with real editors–is the best way to learn the craft. And for whatever reason, it seems that fiction is the best place to learn to write. (This is an opinion, but I have no problem asserting it as undeniable truth.) The technical stuff–most of it–is dry and full of poor writing. I’ve stumbled across countless examples of verbiage in techie books and articles that would make any English professor curse.

I love fiction. Shouldn’t we all? I read much more fiction than non. It would be easy to argue that the skills used to convey well-written fiction have little, if any crossover into a technical career. Don’t say it! (If you already said it, take it back!)

On the contrary, I’ve found that reading quality fiction is applicable my professional career, and its application comes in a form of learning that requires little deliberate uptake. So long as a story holds my attention, reading is easy and fun, and the learning and improving grammar is a secondary, seemingly osmotic benefit. While lost in a great story, we build upon vocabulary and command of language. We see styles and methods that we like. These we recall. We see styles that seem awkward or boring. These we recall as well (and avoid).

I cannot name a single professional career in which the ability to write is not of importance. I’d be interested in hearing of another opinion on this matter. It may sound absurd, as though I am declaring that simple arithmetic is important. But if this is such an obvious assertion, why does it seem that so many communications are written with bold indifference toward basic English?

Lest I get too far ahead of myself, I should come clean with something. The other day I sent my boss a very short email, typed on my iPhone, as I hurried to get things situated at home. The email, I thought, was short and to the point:

Micky-- 
Running a little late this morning. In by 9:30.
-Matt

(Micky is not my boss’s actual name, for the record.) The text above is what I meant to write. It is not what was sent. When I arrived to work, “a little late,” as I had told my boss, he had already had a good laugh at my email. Here’s what I actually wrote:

Micky-- 
Rubbing a little late this morning. In by 9:30.
-Matt

Rubbing. There it was… In my boss’s inbox forever. Foiled by auto-correct again!

Auto-correct is great for very short things, but only when used with caution. In this case it wasn’t a big deal (or was it?). Aside from the hilarity, my boss knew what I meant, and he guessed that auto-correct created the error. As silly as this example may be, it does leave a certain aftertaste, does it not? I’m a technical person, paid for focus and attention to detail. I write software… Software that needs to work the right way every time. While the example above is chuckle-worthy, it is also cringe-worthy. I know better!

Publishing

Publishing articles here and there has been fun. There’s something extremely satisfying about seeing your name in print. (See how I used two adjectives in that last sentence? Don’t do that in a technical document. Ever.) There is a certain thrill in having your words read by an audience. But with this comes a great amount of work and time commitment, which I haven’t consistently had the bandwidth for. To be sure, writing an article for a trade publication must be a labor of love, as the payout for such things is right around $0.00.

It isn’t all that difficult to get an article published, and it may be something worth seeking, if not regularly, at least once. The key is simply to have a specific goal for the article and a certain amount of knowledge of the subject (along with a willingness to put in some research where necessary). When it comes to publishing in a trade publication or website, it is also important to spend time self editing. Most of these outlets don’t edit much (or very well). It is embarrassing to see a typo make its way through to the end product. Even worse, reading a sentence or entire paragraph that you wish you had revised can be infuriating.

Infuriating may be a strong word… Or not. Personally, when reading anything, be it a book, article, or blog post, I lose focus and interest when I become annoyed by an author’s lack of writing skill. And while I am fairly confident that even this post will have a sentence or two that should be reworked, I stand by this assertion!

Keep the grammar simple. If you aren’t sure whether a particular sentence structure works, don’t use it. Lofty language is for poets, not for those of us attempting to convey a point. If a may set aside humility for a moment, the most consistently positive feedback I’ve received over the years has been with regard to my ability to write. What’s the secret here? Nothing, really, at least not that I can pinpoint. (See what I did there? I used a fragment. I love fragments. They are concise. And clever.)

A few things when it comes to software development and writing:

The developer who actually takes the time to document, from commenting code to precise checkin comments to keeping the wiki clean, already has a leg up.
Don’t write to impress. Chances are you will fail. Write to communicate.
Keep it simple, grammatically clean, and to the point… “Pithy,” as Bill O’Reilly likes to say. As I mentioned before, if you believe something doesn’t make sense, rewrite it in a way that you would like to read it.
There is little need to editorialize when documenting software. It may be necessary for certain things, but only in small doses.
Documentation is often treated as something that is done once and forgotten. This is a problem.
We all like to insert humor into our work lives. This isn’t a bad thing. But if there is any chance your words will be read by a customer or outsider of any kind, don’t do it. The words you use may find their way to people considering your company as a partner, client, or provider. Given the fact that the things engineers write may escape the scrutiny of corporate leadership, we should inject professionalism early on.
Have you ever sent a document out to the team for feedback and peer review? When you don’t get any responses (and you probably won’t), don’t assume that this means your document is perfect. It isn’t.
The Oxford Comma is the subject of some amount of debate among literary nerds. I think its use in technical documentation is appropriate.
Semicolons suck. Too strong? Okay, fine. Semicolons are way overused! This doesn’t have much to do with technical documentation, per se. I just couldn’t help but editorialize a bit.