Going beyond a shared understanding…sort of

As a writer working in the software field, I often hear a lot of ideas that aren’t expressed very well. Well, they’re expressed in specifications or in code. They’re just not expressed in actual communication that someone who doesn’t read specifications or code would understand.

And that’s where the technical writer comes in.

Technical writers are like the Bee Gees: words are all we have [1].  If something isn’t detailed, we can’t pass it along as it is to our readers, hoping they will understand. We can either help shape what is there into something comprehensible or we can make it up (but this second option puts the content outside the technical communications genre, and into creative fiction).

For the most part, engineers are like normal people (I said “for the most part”). Normal people and engineers have shared understandings. Most of us are part of communities that share nuances and unspoken ideas. I’m always surprised at how often communication is achieved without words. Often our best communication is not written down. We can get away without words because we share some underlying understandings with our community group.

But shared understandings aren’t complete laws for communicating to others. Rather, these understandings are shortcuts. For example, you describe something I have never heard about before. I ask you if it’s like something that I know about and that I presume you know about. If you hold your hand out flat, palm down, and twist it from side to side, I know you mean, “sort of.”

Most people don’t have to extrapolate from shared “sort of” understandings. In fact, as long as we keep to our own shared understanding group, we never have to explain.

However, a writer is a person who translates shared understandings into words that outsiders can understand. Writers are essentially translators of some world (fictional) or some community (technical) to their readers.

And that’s what I try do.

[1] For the youngsters:

Posted in documentation | Leave a comment

My sensei, my son

I’ve been looking for a Zen master who would take me on as a student. I’ve been looking for this type of a teacher for a long time. The only trouble? I didn’t know that I was looking.

My pilgrimage as a student started the day my youngest child was born. I’m an older father with this little guy, and I find that change is getting harder for me. Not change as in diapers. Change as in personal growth.

At 54, I had forgotten how taxing sleep deprivation can be, both physically and emotionally. I wasn’t at my best. So I wanted to practice peace and find grounding. I’ve read and tried to practice on my own. But I really needed a mentor.

Darn if said mentor came in the form of that little baby. He’s full of koans and knows his dharma. He meditates on bugs, is compassionate to all (when he’s not hungry or tired), and is mindful of each moment.


He’s a happy wonderful Bodhisattva, leading me to embrace life and grow, moment by moment. Just like he does.


Posted in parenting | Leave a comment

The Unbreakable Kimmy Schmidt and Pomodoros

I only watched the Netflix series, The Unbreakable Kimmy Schmidt, once. It wasn’t bad. It just wasn’t great enough for me to commit my time to. There was a quote, however, that resonated with me. Kimmy said, “You can stand anything for 10 seconds.” After that? “Then you just start on a new 10 seconds.”

That’s what I’ve been saying about work that I don’t look forward to. Even in the best jobs–and I’ve been lucky enough to have great jobs for the past decade–there is still work that I find dull, overwhelming, or trite.

Thank goodness for the Pomodoro technique.

The Pomodoro technique segments a task into one or more 25-minute periods. I work on a task for a period of time, called a pomodoro (Italian for tomato). When that time is up, I take a break for five minutes. Then I repeat until the task is done.

It’s simple and painless. Somehow, that little act of setting the timer clarifies my thoughts and helps me take on overwhelming (and underwhelming) projects.

I’ve been using the Pomodoro technique for years. I’ve come to rely on it for things I don’t really want to start, or continue, or finish. Using a time segment of just 25 minutes, I have found that, like Kimmy Schmidt, I can stand anything for 25 minutes.

After that? Then I just start on a new 25 minutes.

For more information about using Pomodoros, see:

Posted in writing | Leave a comment

Communication Hubris

From the Googles:



excessive pride or self-confidence.
synonyms: arrogance, conceit, haughtiness, hauteur, pride, self-importance,
egotism, pomposity, superciliousness, superiority; More
antonyms: humility

(in Greek tragedy) excessive pride toward or defiance of the gods, leading to

Just when I think that I’m a great communicator, life enlightens me and shows me that I am deluded. This enlightenment usually takes the form of a small child.

You really have to be a great communicator to help children understand things. Not even ethereal concepts. Just ordinary things. Like hats.

              (pointing to one of many caps in the closet) 

Yes, that's a hat.

  (pointing again to another cap) 

Yes, that is also a hat.

 (pointing to yet another cap) 

          That is a hat as well. I could add that 
           the hat is actually a cap, but we'll get 
            into subsets when you're older. Actually, 
            each hat you've pointed to is technically 
 a cap. But there are some hats 
hanging in the closet as well.

(pointing to first cap)

Sorry: yes, that is a hat.


I wonder whether my youngest child would be better served by me just shutting the heck up. I’m not a poor communicator. Most of the time, anyway. I’m actually a pretty decent communicator. I make a living at it, for crying out loud.

It’s just that I’m not in the 90th percentile. My child reminds me that, on a good day, I’m solidly entrenched in the 60th percentile.

Posted in communication, parenting | Leave a comment

A Luddite’s Take on Cloud Implementation

In 1987, farmer, essayist, and poet Wendell Berry offered up his standards for technological innovation:

  1. The new tool should be cheaper than the one it replaces.
  2. It should be at least as small in scale as the one it replaces.
  3. It should do work that is clearly and demonstrably better than the one it replaces.
  4. It should use less energy than the one it replaces.
  5. If possible, it should use some form of solar energy, such as that of the body.
  6. It should be repairable by a person of ordinary intelligence, provided that he or she has the necessary tools.
  7. It should be purchasable and repairable as near to home as possible.
  8. It should come from a small, privately owned shop or store that will take it back for maintenance and repair.
  9. It should not replace or disrupt anything good that already exists, and this includes family and community relationships.

These tenets were published in an essay, “Why I Am Not Going to Buy a Computer.” And, being the contrarian that I am (and both a Berry fan and a technologist), I wonder: Can we use these standards for cloud adoption? I will try.

Cheap: Going to the cloud for either storage or computer processing can be cheaper than buying a new computer. Depending on  your storage needs, it can also be cheaper than buying a new drive. So, that’s one.

Scale: The scale of virtual machines is as small or as large as you need. And, when you’re done using it, you can terminate it and not have to worry about recycling the box it’s in.

Work quality: Depending on your current hardware setup, a cloud-based solution can (not necessarily will be) better and faster than your current machine.

Energy: If your storage is on an external drive, then cloud loses this one. But if your computational needs are intensive but not often, a virtual machine wins this one.

Solar powered: We’re tied here. Come on solar-powered machines.

Ease of Repair: If you’re a hardware person, having your own storage or computational solution at hand wins out here. If you’re not a hardware guru, it’s actually pretty good to have a cloud solution because you can get help with any problems. This help can be either the cloud provider or your fellow users.

Local provider: Okay, this one is a draw. I think Mr. Berry (who would probably be appalled by this post anyway) would be laughing at me.

Local maintenance: Small computer shops are going away but, while they’re around, the cloud solution loses this one.

Lack of disruption: Technology is usually about disruption. Computers disrupted paper. Cloud disrupts private technology. Berry probably wouldn’t see any difference. We’ll call this one a draw.

Looks like the cloud wins. I’m going to write to Mr. Berry and let him know.

Posted in cloud | Leave a comment

Goodbye cloud. Hello big data. Oh yeah: nice to see you again, cloud

This week I started my new gig at Cloudera. I’m quite excited about the opportunity. Although, I already miss my colleagues and friends at Eucalyptus.

It’s a big change for me. For the first time in seven years, I won’t be documenting infrastructure.

Except that I will. Big data in the cloud.

Posted in documentation | Leave a comment

Thanks for Nothing: Help that Sucks

I love Amazon. I used to work there for years. Most of their documentation is really good. However, I found the following help for downloading Kindle for Mac to be . . . well . . . please refer to my previous utterance, in the title for this post. (Hint: It rhymes with “bucks” and “shucks.”)

I searched for “Kindle for Mac download” and got this page on the first hit:

Image of sucky help page on Amazon. The first step reads, "Wait for the download to complete."

Okay, “wait for the download to complete”? What download? And there’s no TOC or breadcrumbs anywhere that points to more context. Sure, I could download it from the App Store. But I loathe the App Store (speaking of crappy interfaces).

And, even if there’s another way to perform a task, that doesn’t mean someone should  publish a set of steps that requires extra insight and context not included in the page. How about a link? Or breadcrumbs? Or a TOC?

(Note to self: make sure you didn’t create the Amazon page in question. If you did create it, delete this post.)

Posted in documentation | Leave a comment