Good gravy, I’ve been away from posting for a while. I decided–crazy or not–that in 2017  I would try to read 200 books. As the year nears its end, I finally figured out that this goal was not so worthy.

11 months later. I’m a slow learner, apparently.

Anyway: I’ve enjoyed most of the books I read but I found that I had very little time for other things I enjoy. I didn’t practice guitar as much. I didn’t write. I didn’t train my dog enough. There was a lot of life that I missed.

So, as much as I love learning about things, I sure as heck love just being and enjoying. As much as I love consuming, I kind of like producing something too.

Next year, I’m going back to my 100 books a year routine. I might even try to work on being friendlier. But that’s going to require more than one year.

Posted in books | 2 Comments

Encouraging geekiness and combatting sexism

My two-year-old loves superheroes. He has books about and toys of Spiderman, Ironman, Wolverine, Wonder Woman, and many others. He doesn’t understand gender yet. So when we play, he assigns mommy’s role as both Storm and Hulk. On any given day, I can be either Cyclops or Marvel Girl.

He’s at a great age and I don’t want to screw things up…any more than I have to. Coming from a non-geeky upbringing, the comic world seems so sexist to begin with. What to do when a child chooses their passion? Let them and try to correct when needed.

When we read about the X-Men, we tell him they’re called the X-Heroes. This might confuse him a bit, but I sure don’t want pass along some nomenclature that was the norm for Stan Lee in 1963. Hopefully, he will see the use of “men” for “people” as an archaic and out-dated way of describing us all.

Small steps.


Posted in parenting | Leave a comment

Security Layers for Lunch Retainment

A colleague of mine recently reported that her lunch salad had been stolen from the refrigerator at work. In the grand scheme of things, this is probably no biggie, and my colleague was able to laugh about it.

But seriously: who the hell steals lunch these days?

It got me thinking of ways to prevent such lefts. Sure, we could implement the Internet of Things and fit lunch bags with tracking devices. But I have an easier solution, implementing security levels to stop the groups of lunch thieves.

Layer 1 Protocol

At this level, we put ranch dressing on the salad. This stops the vegans.

Layer 2 Protocol

At this security level, we place shredded chicken and/or pork throughout the salad. This stops the vegetarians.

Layer 3 Protocol

At this level, we place rat poison in the salad. This will kill off the vegans and vegetarians because they think the normal laws of physics don’t apply to them. It will also thwart the carnivores who, upon seeing a dead comrade, are smart enough to understand that they need to change their evil ways. Plus all the vegans and vegetarians will be dead. It’s a win-win.


Posted in office | Leave a comment

Whining: the other side of advocacy

One of the arts of any craft is learning how to deal with colleagues. And part of this is learning the give-and-take nature of relationships.

I love the passion that comes from advocating a position strongly held. It’s good not to give up. Well…until it’s time to give up.

At some point, advocating a lost cause leads to whining and grumbling. Take it from me, I have sojourned into the whiny realm on a few occasions, bringing a tent, dehydrated stews, a pound of coffee, and a latrine shovel. I’ve been ready to camp out and make my point.

But the point at that point is moot. Move on, literally or figuratively. Don’t force people into what they don’t want to do. Ask  yourself if you’re correct and, if so, whether it’s worth fighting for. If it’s worth fighting for, it’s usually only worth waging the battle for a bit. Then you either drop it or find a new place to work.

There’s no harm in moving on. There is harm in nagging.

Posted in documentation | Leave a comment

Using Coltrane changes in documentation

In jazz, there’s a common method to get from one place in a progression to another. It’s called the two-five device (really it’s ii-V, but I want to convey that that it’s pronounced “two-five”). In music theory, the five chord wants to resolve to the one or the tonic, that is, the key that the song is in.

Coltrane found a way to get back to the tonic by using a series of ii-V devices that go up minor thirds. This method of moving around is called a Coltrane change. It sounds complicated, but just know: it’s a way to move around in a song and still get where the song needs to go. A Coltrane change is just a series of chord substitutions, and using substitutions is a common device used in jazz.

Coltrane changes remind me that no matter how well I design a documentation set, there are people who find things differently than I expect them to. I need to account for my readers by offering alternative ways to get to the content they want. They can use the TOC or an index. However, most readers won’t use these archaic methods. Most of my readers will be using search or links. So I try to give them richer links and better search metadata, the ii-V of documentation.

Posted in documentation | 2 Comments

Ba-dee-ya, publishing tomorrow

In the spirit of wabi-sabi, I’m thinking about using “ba-dee-ya” as a placeholder for my unfinished content. I have some deadlines that I won’t make and, rather than commenting out entire sections of text, I think I’ll include what I can, using “ba-dee-ya” where there’s more to come.

Maurice White of Earth, Wind & Fire passed away this week. I’ve been singing the song, September, for days now. Great song. It sounds a tad unfinished, with the “ba-dee-ya” in the chorus, but it’s still a great song. And I sing it. And dance to it.

I read an interview with one the songwriters, Allee Willis. She said that Maurice would use “ba-dee-ya” often as a placeholder for lyrics until the lyrics were finished. In the case of September, Maurice was good to go with keeping all the “ba-dee-yas” in place. It was not only good enough, it was the right fit.

Sometimes I need a ba-dee-ya rather than anything polished. To paraphrase Allee, I shouldn’t ever let my text get in the way of stating something important. Time to create a September-ipsum.

Posted in documentation | Leave a comment

Context and confusion and twins

I’m a big fan of Every Page is Page One design. One of the tenets of an EPPO topic is that it sets the context for the content within that topic. This way readers don’t have to rely on our breadcrumbs or TOC or other forms of nested structure.

Context is imperative if you want to help your readers out immediately. It can be the difference between an instant “okay, yes, this is what I want” and “Sugar-honey-ice-tea, I just read for 20 minutes and finally found out that this topic is irrelevant.”

A few years ago, after one of my daughter’s soccer games, I was talking with Hannah, one of the mothers on the team. While we were chatting, I noticed her husband walking across the field. I took notice because the husband, Daniel, was being followed by a little boy. Hannah and Daniel don’t have a little boy, so I assumed this was a nephew or just someone who was tagging along because Daniel is a kind and gentle man.

When Daniel and the boy got closer, Hannah asked me if I had ever met Daniel’s brother. I looked at the boy and said, “No, I haven’t.” I thought, “that’s quite an age difference.” Hannah then said, “Yeah, they’re twins.”

Now you, kind reader, probably see what Hannah meant right away.

Not me. I have what my wife terms “attention surplus disorder.” I don’t let go of what I’ve already locked onto.

I looked at the boy and back at Hannah and asked, “What?”

She said, “Twins. You know what twins are, right?” I could see fear rising in her eyes because her daughter spent the night at our house and maybe she assumed that if I don’t know what “twins” are, perhaps I don’t know what an “emergency” is.

“No, I know what twins are. But…how?”

“Uh, well the normal way.”

By this point, I’ve already gone through the scenario: separating the fertilized eggs and cryogenically freezing one for three decades until they thawed it and artificially inseminated a volunteer. But did they have that technology back then? And, if so, why would they have done that? And what is cryogenic freezing? Is it different than flash freezing or regular freezing? And how come they had to separate Ted Williams’ head from his body when they cryogenically froze him after he died?

And then it hit me: I pointed at Daniel and said, “Oh, that’s not Daniel!”

Hannah looked at me like I just told her that the sky is blue. “Right, that’s what I said.”

I pointed to the boy next to the faux-Daniel: “And this is?”

“That’s my nephew.”

“The son of Not Daniel.”

She looked at me and smiled. “Right. Like I said, Daniel’s twin.”

Now, I’m not saying all of our readers are as clueless as I am. But unless we establish context, many of our readers are going to be confused about what we’re talking about.


Posted in documentation, EPPO | Leave a comment

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