My first road race

A while back, I wrote that to be successful, you need to step out of your comfort zone.

I just stepped out of it in a big way.

I just registered for my very first road race: the 2019 CDPHP Workforce Team Challenge. I have never run any kind of registered road race* before. This will be my first.

(*I have, however, participated in a registered bicycle tour before. But I feel a lot more comfortable about my bike riding than I do my running.)

I will say that running and I have never really gotten along. It is not, I repeat, not one of my favorite physical activities.

I’ve been active in CrossFit since 2015. I’ve made big strides since I started. Although I still have a lot of things that I need to improve, I can do a lot of things now that I couldn’t when I first started.

And as it turns out, one of the things upon which I’ve improved is running. One particular coach tends to push me pretty hard (in a good way). Whenever a 5K run has come up in a CrossFit WOD, I’ve toyed with scaling it down to a shorter distance. It was this particular coach who said to me, “nope, you’re not scaling it. You’re running the full 5K!”

And it’s for that reason why I feel I’m capable of participating in this event.

Granted, I use air-quotes when I say “run.” It’ll probably be more like some jogging, some walking, and some stumbling. (And this event is longer than 5K; it’s actually 3.5 miles.)

If you want to get better, you need to step out of your comfort zone. I’d say that this definitely qualifies.

For reference, my best 5K time is 50:18. We’ll see how this goes. Wish me luck.


The symbiotic relationship between documentation and application development

One of my current projects involves documenting processes for an application that are still under development. As such, much of what I write may change, depending on how processes are changed during the course of development.

At one point, I tested one of the processes so I could determine functionality and document it. In doing so, the process came back with an error message that I wasn’t expecting and didn’t have any user-friendly information, other than a cryptic error code. I contacted one of the developers working on the application and told him what I found. I gave him the error codes I experienced and steps I took to get them. He told me, “you’re coming across bugs that we didn’t even know we had.”

It occurred to me that I was doing more than just documenting the application. I was also acting as a beta tester.

One aspect about writing technical documentation is learning about what you’re writing. In order to write about a process, you need to understand how it works. If you’re documenting an application, the best thing you can do is run the application in a safe environment (such as development or a sandbox), learn how it works, and use it to document steps and capture screens. In doing so, you come across application bugs and even come up with ideas to make the application even better.

I’ve long argued as to the criticality of documentation. It records important information and serves as a reference. However, until this point, it didn’t occur to me that the document development process could have a symbiotic relationship with application development. To me, this adds further fuel to the argument that documentation is critical and required.

Don’t forget to edit your system messages

One of my current work projects is a administrative guide for our application. After a recent status meeting, one of the developers sent me a list of validation error messages that might appear during data imports. I was asked to make sure the validation messages were included with the documentation.

While going through the validation messages, I noticed that they were filled with grammatical, capitalization, and spelling errors. I asked the developer if he wanted me to edit the messages, to which he responded, “yes, please!”

People don’t think about checking output messages for correctness during application development. It is often a part of applications that is overlooked. For what it’s worth, I, myself, didn’t even think about it until I was asked about these validations. Nevertheless, reviewing and editing output messages is probably a pretty good idea.

For one thing, and I’ve stated this before, good writing reflects upon your organization. Well-written documentation can be indicative that a company cares enough about their product and their reputation that they make the effort to produce quality documentation as well. Well-written system messages indicate that you care enough to address even the little things.

Well-written error messages can also ensure better application usage and UX. A good output message can direct an end user to properly use the application or make any needed adjustments. Messages that are confusing, misleading, badly-written, or ambiguous could potentially result in things like application misuse, corrupted data, accidental security breaches, and user frustration.

Ensure your application development review and testing also includes a review of your system messages. It may be a small thing, but it could potentially address a number of issues. As someone once said, it’s the little things that count.

Dont rite so gud? Don’t let that stop you

Eye no that a Lot of ppl dont Right to gud. That shudnt keep ppl frum Riteing. Lot’s of ppl dont Right gud.

Did you have trouble reading that paragraph above? I actually had trouble writing it. The late Harry Chapin had a song called Six String Orchestra in which he intentionally plays badly. I once said that if you’re an accomplished musician, one of the most difficult things to do is to intentionally play something badly. If you’re a writer, I suppose the same is true for intentionally writing something badly. I remember reading a novel, Flowers for Algernon, in which a mentally-retarded man, writing in the first person, increases his intelligence after an operation. It was interesting reading the account as his intelligence and his awareness increased, and I can only imagine as to how challenging it might have been to write.

Anyway, in my technical writing presentation, one of the points I try to make is that not being able to write well should not discourage people from contributing to documentation.

I’m the first to admit that I’m a grammar snob. I’ll often be that person who is “silently correcting your grammar.” I cringe anytime someone doesn’t know the difference between “your” and “you’re.” I have to hide my eyes anytime someone uses an apostrophe-S as a plural. And I still believe that anyone who says “irregardless” should be flogged.

That said, I understand that not everyone is a good writer. Just because someone does not write well doesn’t mean that person should be discouraged from writing.

For one thing, as I said before, everyone has to start somewhere. Someone once said that “one of the dumbest quotes ever coined is ‘do it right the first time.’ It’s almost NEVER done right the first time.” And the one sure-fire method to improve is to practice. The more you write, the better you’ll get.

If I had to offer a piece of advice to someone who wanted to get better at writing, I’d suggest reading material by your favorite author, then try emulating that author’s style. For example, a few of my favorite authors include Stephen King, Tom Clancy, and Terry Brooks. I enjoy their books and their writing style. After reading their works, I found myself wanting to emulate how they write. I discovered that, over time, my writing kept getting better.

For another thing, an inability to write well doesn’t mean a person lacks intelligence or knowledge in a subject. That person often contributes to documentation as a subject-matter expert (SME). An SME has a great deal to contribute, but knowledge transfer can be challenging. To be fair, this is not an easy thing to do; one of the most difficult tasks is to communicate knowledge to other people. (I even have an entire presentation about this.) People often have valuable information to contribute; the challenge lies in how to convey that information. If someone with information doesn’t write well, that shouldn’t stop him or her from doing so.

Granted, if a piece of writing needs to convey a “good face” (say, client documentation or marketing materials, for example), then it’s important for it to be well-written. But if it’s a mere matter of knowledge transfer, it’s more important that a concept is written down rather than not be written at all. If an idea needs to be cleaned up, go ahead and write it down, and let someone else do the grammatical heavy-lifting. Not being a good writer should not be an impediment to writing at all.

Testing is important for documentation, too

For those of you who produce documentation, how often have you sent your documents out into the real world, only to have it returned to say it’s all wrong? Or have you ever received feedback saying things like “this is difficult to read,” “I can’t follow this,” and so on?

One of my most frustrating aspects of technical writing is any time — every time — that I ask people to review what I write, my request goes ignored. As I’ve written before about the nature of documentation, requests for document review are often met with indifference and disrespect. A lot of people just don’t think it’s important. It is critically important. I don’t always know about the subject that I’m writing, and I’m often at the mercy of subject matter experts (SMEs) who know more about the subject than I do.

It’s not just the subject matter, either. I’m the first to admit that I’m a grammar snob, but I’m also not perfect, either (I was not an English major, after all). Many a time have I confused “who” and “whom,” ended a sentence with a preposition, used an apostrophe-S for a possessive, forgotten to put “I before E,” and so on. Likewise, I try my best to design documentation for better readability, but I also realize that there’s always room for improvement, and it often takes another set of eyes to provide a way to make something better than never occurred to me.

I’ve argued before that documentation needs to be treated like software. Like software, documentation has a life cycle. It needs to be maintained. And as such, it needs to be tested. Documentation, like software, will have bugs that need to be addressed.

It also isn’t just a matter of reading a document and saying “yeah, this looks good.” User testing should also be a part of it. If you’re writing step-by-step instructions, how will you know if they’re accurate? Back when I was a grad student at RPI, one of my writing projects included user testing as part of the project. I wrote a set of instructions for a procedure in my office (the document served a dual purpose for me — not only was I getting graded for it, I was also contributing to my workplace). To test it, I asked one of my co-workers to follow it as she went through the procedure I’d documented. She caught issues with my steps that I never would have caught on my own. From that user testing, I corrected the issues and made the document even better.

As a technical writer, I expect — and demand — people to review, test, and scrutinize what I produce. I demand excellence from myself. In order to achieve excellence, I need other people to review what I do. And I want to know that what I’m producing is of good quality and factually accurate. Without that critical feedback, I’ll likely not know whether or not I’m doing my job.

The CrossFit Open 2019

This morning, I registered for this year’s CrossFit Open, which starts tonight. This is the third time in four years that I’ve signed up for the Open. (I was unable to participate last year due to commitments and subsequent time constraints.) Thousands of participants from around the world, representing many age groups and skill levels, participate in the Open. The best of them go on to the CrossFit Games. (The Games are represented by world-class-level athletes, of which I’m not even close, so don’t expect to see me participate at a regional anytime soon!)

Why participate in the Open? For one thing, it’s an opportunity for pseudo- couch potatoes athletes like me to take part in such an amazing event. Think of it as a Little Leaguer competing on the same field as, say, Aaron Judge. For another, it’s a measure of how far I’ve come in CrossFit since I started doing it over four years ago. When I first started, I couldn’t hold a squat without falling over on my backside. Now I can hold one almost indefinitely. Granted, I still have a long way to go — I still am unable to do anything involving pulling myself up (pull-ups, rope climbs, etc.) — but I continue to keep at it. Maybe someday, I’ll get them! It’s also a measure of how you do against your peers. You’ll get an idea as to how you stack up against similar athletes.

Other reasons? Well, let me, once again (as I’ve done several times before), quote one of my favorite song lyrics by my favorite band

“Gotta run a little faster, gotta reach for the sky, gotta come a little closer, even if I lose, I gotta try…”

“Inside Of Me” by Kansas

If you want to see how I do over the next five weeks, click here to check out my Open profile. We’ll see how this goes!

Wish me luck!

When it isn’t appropriate to say “please”

I recently ran a work report that provided a list of diagnostic descriptions within our application. These diagnostics are stored in a database table, and they appear when an issue is encountered within the application. They provide an error code, a description, and a recommended course of action.

I was running this report so I could document the application used to generate the report. But when I looked at the results, something struck me.

There were sixty-one active diagnostics. Looking down the column containing the recommended courses of action for each diagnostic, something stuck out at me like a sore thumb.

In EVERY SINGLE action, the first word was “Please.” Every single action started with “Please ask…” or “Please perform…” or “Please do this…” Every. Single. One.

I was raised to be polite. My mother always taught me to say “please” when asking for something. For the most part, I agree with this. All children should be taught to say “please” and “thank you.”

That said, this is not appropriate in most professional-level technical communication.

When you’re writing technical instructions, you are telling someone how to do something. You are NOT asking someone for a favor!!! This is another one of my technical writing pet peeves. Writing professional technical instructions involves using language that’s direct and to-the-point. Unless the tone of your document is laid-back or colloquial (the “For Dummies” series of books comes to mind), it is NOT supposed to be conversational.

Now, I’m sure a number of people reading this might not agree. It should be pleasant to read, you might say. Here are the reasons why I don’t agree.

Instructional language should be neutral. See what I wrote above. I’ll say it again: you’re telling someone what to do, not asking a favor. You’re trying to get your reader to complete a task, not trying to make friends with him or her.

It’s extraneous. One of my tenets of writing instructions is that it needs to be as simple as possible. In my documentation presentation, one of my major points of emphasis is the KISS principle. A big part of keeping it simple (which, granted, isn’t easy) is to eliminate anything extraneous. Extra words add complexity. The less complexity that’s in an instruction, the better.

It’s annoying. When you’re reading a set of instructions, reading “please do this” and “please do that” gets old after a while. I’ve read instructions like that before (including the report I describe at the beginning of this article), and by the time I got to the end of the document, I wanted to slap the writer more than I wanted to finish the task.

When you’re having a conversation, saying “please” is very much appropriate. But technical writing is not a conversation. Conversational language is not appropriate in professional technical writing. As a technical writer, I’m imploring you: please stop saying “please!!!”