In William Shatner-ese: Must. Work. Can’t. Blog.

I’m a few days out from the Write the Docs conference. Once again, the conference planners did an amazing job. I’d like to blog more about it, but I’m under a deadline. I have 17 days to finish about eight years worth of work.

Piece of cake.

It was wonderful to see old colleagues and friends, and meet new ones. I’d love to blog about what I learned. However, I have no time for such frivolity. So, to both of my readers, let me offer you some other places to get the scoop on Write the Docs 2014. These folks did an amazing job capturing everything from the whole to the gist.

Posted in documentation | Leave a comment

Teaching My Daughter to Drive a Car…and Mentoring Others

Getting a driver’s license is about as far as we go in our society for giving our adolescents a rite of passage into adulthood. To me, it’s almost a sacred time (okay, and a scared time, just to be anagram-istic).

My daughter did well her first time out. I expected as much. She’s careful and observant. One of the things I like about teaching her how to drive is that I get to spend more time with her, with the accompanying memories in the making. I’m a lucky man.

Image

This reminds me of the time I spent at a larger company mentoring younger writers. I can’t vouch for them, but it was an almost sacred time for me, the passing along of collected information. Now at a startup with a much smaller writing team, I don’t get a chance to mentor any more and that makes me feel like I’m irresponsible with my knowledge.

So, to both of my readers out there, I’d like you pass along this offer to any budding writers/technical communicators: I’m here to help out with the twists and turns of our shared career choice. If anyone is out and needs some help, write me and we’ll go out for a driving lesson. That’s a figurative tie-in with my observation about teaching my daughter to drive . . . oh, you got that. Okay, just wanted to make sure.

Posted in parenting, writing | 2 Comments

The Sphinx Kool-Aid Looks Great…But I Don’t Want to Drink It

After 16 years using XML, I’ve been tempted to switch to Sphinx. My new colleague at Eucalyptus, Kushal Das (http://kushaldas.in/) , has asked me to think about switching our DITA content to reStructuredText (reST).

I tried Sphinx last year at the Write the Docs conference. It’s pretty impressive, especially in that it’s lightweight. This is a big plus in terms of our community. Currently, anyone who wants to contribute content has to fork a h-u-g-e repository that includes tons of tools necessary to generate content.

It’s not pretty.

However, XML offers so much…that and I hate change. However, if it benefits our community, I’m willing to use crayons and paper cocktail napkins.

Have you gone from XML to reST? If so, please let me know what benefits you found.

Posted in documentation | 5 Comments

Geez, I forgot how time-consuming a baby is…

This little guy is keeping me from blogging. Not complaining. Just explaining.

Image

Posted in documentation | Leave a comment

So, 29 Years After My Oldest Was Born, I Adopted Again…

Cedar was born on June 9th. That’s why this blog has gone dark for a while.

Well, that and I’m a lazy ass.

Back to Cedar: Holy cow. You’d think after parenting for nearly 30 years, I’d have some father-like chops in the repertoire. Nope. That poor little guy gets a dad who seems to have forgotten everything he ever knew about parenting. I might as well be 17.

So I’m still reading about parenting, and trying to figure stuff out as I go. Often with the help of the older kids. For example, when talking hypothetical situations: “Dad, I hated when you did that. Maybe you should change your strategy.”

But with some memory coming back, talking with the other kids, reading and a little luck, I hope that I’ll make some new mistakes with Cedar. That’s the goal: not no mistakes, just new ones.

And, just to artificially tie this in with the other writing/tech comm/cloud themes in this blog: I’m still reading, still talking to others involved in the industry, and still trying to make new professional mistakes. One possible mistake-in-waiting is the commenting system I’m going to roll out for the Eucalyptus documentation. It’s the best one that I know of–that’s the not the possible mistake. The possible mistake is that it won’t be the same forum/commenting system used in our support area. That could be a problem with single sign-on, but we might be able to unify the two. We’ll see.

Maybe I should talk to my kids and see how they feel about it.

Mistakenly yours,

Scot (new parent . . . again)

Posted in documentation, parenting | Leave a comment

Lonely Island’s Semicolon

Exactly.

Video | Posted on by | Leave a comment

Not Dead: Responsive Communication

My wife occasionally sends me text messages which, in my mind, do not require a reply. You know, things like a status update or a quick note that she’s running late. It’s informative for me to know.

However, I didn’t know that such things require a response. She told me that she would like a response, just to ensure that I got the message…or to let her know that I’m still alive.

So, our standard response to messages of seemingly non-required response is this: “Not dead.” This two word phrase can mean “I got your message. Thanks.” Or “Sounds good.” Or “Hmm. Interesting.” Or even “I am, in fact, still a member in good standing with the Living Bipedal Organisms on the Planet.”

Image

Anyway, it struck me that the informational cues that I take for granted, might not be so universal. If my wife and I don’t share all communication understandings, how then am I messing up with readers who refer to publications I write? My wife and I have an established relationship. The relationship has created lots of room for each of us to understand any potential misunderstanding.

In business, however, there is no such relationship. You have to meet the needs of customers, and meet their needs where they are–in locale, emotional state, or technical expertise. So you don’t have latitude to let a message slip through, offering no response.

My advice: never let a message go unanswered. Even if the message isn’t a question or something that wouldn’t merit more than a “hmm” in face-to-face interaction. In digital interaction, you have to acknowledge that the writer has been heard from.

Or at least that you’re not dead.

Posted in documentation, writing | Leave a comment

Wabi-Sabi Writing

My limited understanding of the Japanese concept of wabi-sabi is that it is an insight in which you can appreciate the beauty in the imperfect, impermanent, and incomplete.

I don’t know about things you write, but imperfection, impermanence, and incompleteness are three qualities of most documentation. These traits certainly explain our documentation for Eucalyptus, the company I work for.

Eucalyptus is open source software for building Amazon Web Services-compatible private and hybrid clouds. Documentation for public clouds has really only been around for seven years. Private and hybrid cloud documentation has only been published for about four years. There are very few writers working in this area, but there is a lot of engineering going on that needs to be documented.

So, as one of the few writers in the arena, you’d think I’d be happy just being here. However, I have a confession: I struggle with trying to make a “done product,” even in an area like cloud computing. I long to create something that is permanent, perfect, and complete. On my best days, I realize these lofty goals are my enemy. On my worse days, I want to wait before I publish something that I’ve written, even if what I’ve written might be good enough, however imperfect. I want to polish and shine things until I deem them ready. In other words, I never want to publish.

You see, I’m bound by two opposing factors in my writing:

  1. I don’t like imperfection, impermanence, and incompletion in documentation.

  2. I have never written anything perfect, permanent, or complete in my professional life.

Number two probably won’t change. So I can either change my feelings about number one, or learn to live with it.

I’m not willing to give up the goal of writing perfectly, completely, and producing something that stands the test of time. However, I might be able to live with the fact I can edit and hone and further shape existing imperfect material that I write, in order to make it closer to what I can live with.

This summer, Eucalyptus will enable comments to our documentation. You can tell me on the web page what you find to be incomplete, incorrect, unclear, maybe too verbose. Let me know. Trust me: I know our documentation has a ways to go.

And I’m learning to be good with that.

Posted in documentation, writing | 2 Comments

The Writing Life: Ernest Hemingway

“Since I had started to break down all my writing and get rid of all facility and try to make instead of describe, writing had been wonderful to do. But it was very difficult, and I did not know how I would ever write anything as long as a novel. It often took me a full morning of work to write a paragraph.”

A Moveable Feast, p. 22

Image

Posted in writing | Leave a comment

Semi-colon-oscopy

Stop using semi-colons in your technical documentation. You can stop reading now if you pledge to delete your semi-colons. If you don’t make such a pledge, read the rest of this riveting blog entry.

I used to use semi-colons in my docs a lot. I garnished my paragraphs with them like they were free. Why? Well, there’s a feeling that semi-colons make you looks smart. And, well, they ARE free.

But in the technical world, this type of punctuation is too difficult. Readers don’t know if you’re trying to tie two points together in one sentence or what. It’s like replacing stop signs with  roundabouts in America. Sure, many drivers know how to navigate the circle. But many of us just sit, idling the car with the breaks on, fearing to enter the intersection.

Just keep the stop sign. Everyone knows what to do.

Same with the semi-colon. Stick to simple sentences to make your points or tell your story. Use simpler, shorter sentences that each end with a period. A period is a stop sign that helps your readers navigate through the content. Your translators will love you, and your readers will better understand what the heck you’re trying to say.

Save the flair and style for boring blog posts about punctuation; that was a joke.

Posted in documentation, grammar, writing | Leave a comment