Technical Writing Joys and Woes

Planned absence

doug@dougcuff.name (Douglas Cuff) — Wed, 17 Sep 2025 07:00:00 -0400

In the past, I stopped updating this site because of either technical issues, or because life just kept me too busy.

This time, I can see it coming: I’m going to have to go quiet on this site because that’s what my life requires of me. I hope to be back soon, but I can’t guess when that might be.

New technology is not exempt from principles of design

doug@dougcuff.name (Douglas Cuff) — Fri, 15 Aug 2025 08:00:00 -0400

I’ve been a technical writer for about 25 years, but a friend of mine has been a technical writer for 35 years.

This friend recently pointed out that creating professional-looking output still requires you to become a desktop publisher, same as it did 40 years ago. Creating and crafting text (writing) is easier, but presenting that text to the reader (publishing) still requires a broad skill set that includes design.

What customers value

doug@dougcuff.name (Douglas Cuff) — Sat, 09 Aug 2025 08:00:00 -0400

If you ask customers what they value, they will tell you. Obviously, first you have to be smart enough to ask them, and then you have to be smart enough to listen.

In 2024, a major firm asked its customers what made them likely to recommend that firm. The ten most frequent responses were ranked from 1 to 10, with 1 being the most important.

The most important factor was customer support. Fully 12% of customers said that mattered more than any financial considerations, including payment terms and price.

Are you communicating?

doug@dougcuff.name (Douglas Cuff) — Tue, 17 Jun 2025 08:00:00 -0400

When you write, are you improving the life of your reader – or at least, improving the reader’s understanding? The people who think that writing is easy have deluded themselves that it’s just a question of bunging some words down on the screen.

Writing is not dedicated to the proposition, “All right, let’s get this over with.” But we are all being bombarded with examples of that perfunctory style of writing.

Apologies for temporary technical issue

doug@dougcuff.name (Douglas Cuff) — Thu, 01 May 2025 13:00:00 -0400

UPDATE: The problem literally was with the remote system. It broke itself and it fixed itself without my intervention.

The system that I use to display images on this blog has stopped working. I will try to determine why, I will try to fix it… and I will definitely try to find a replacement for it.

Revising legal language

doug@dougcuff.name (Douglas Cuff) — Tue, 22 Apr 2025 13:00:00 -0400

When it comes to legal text, the technical writer’s first rule is simple:

Do not change any text that a lawyer wrote.

There are legal reasons why disclaimers, copyright notices, privacy policies, and other examples of fine print were phrased the way they were. Under no circumstances do you “clean them up” after the lawyers are done. No revisions.

Your superpower is communication. Theirs is the law. Law trumps communication.

Why smart tech writers still matter in the age of AI chatbots

doug@dougcuff.name (Douglas Cuff) — Fri, 11 Apr 2025 16:00:00 -0400

The chatbots that rely on generative artificial intelligence have their uses, just as Wikipedia does. But relying on the details that either tool provides will land you in trouble eventually. In the case of AI chatbots, you’ll be in trouble sooner.

The common term for chatbot error is “hallucination,” and that’s already a dangerous term. A chatbot is technology, not a person or a character or a pet. It can’t hallucinate; it can present false claims confidently and with an air of authority. The most recent chatbot models continue to reply to queries with errors; this is not a problem only with earlier versions.

One writer's superpower

doug@dougcuff.name (Douglas Cuff) — Tue, 08 Apr 2025 07:00:00 -0400

I have a laser focus that you’re not going to believe. I’ve had this superpower even before I became a writer. But non-writers think I’m exaggerating. If you’re a savant, it’s no big deal to you that you can count how many toothpicks fell out of a box onto the floor in just one glance. But if you’re not, it seems impossible.

Yesterday, I picked up a medical brochure in a doctor’s waiting room. I skimmed the front cover without really reading it, then I flipped the brochure over… and instantly saw the error: “indiviual.”

Can anyone be a writer?

doug@dougcuff.name (Douglas Cuff) — Mon, 24 Mar 2025 13:50:00 -0400

Can anyone write?

That depends. It depends on what word you mean when you say “write.” Do you mean “make letters on a surface”? Or some other definition?

“Can anyone write?” is a subject for a longer post. I’ll get around to writing it. Someday. Let’s ask the question a different way:

Can anyone be a writer?

No.

I own a phone with a built-in camera. I sometimes use that camera to take photographs. That does not make me a photographer.

Why no blog updates for the past eight months

doug@dougcuff.name (Douglas Cuff) — Thu, 06 Feb 2025 08:50:00 -0400

As I mentioned in Why no blog updates for over a year, I ran into some problems with Jekyll, the framework I used to publish blog entries. I eventually fixed the problem. Then I tried to update Jekyll. Which caused different problems.

So I’m done with Jekyll. I’ve moved to Hugo. While that is the name of Martin Scorscese’s only film for children, it’s also the name of another framework for generating websites (from Markdown files).

Meeting another reader

doug@dougcuff.name (Douglas Cuff) — Mon, 20 May 2024 10:25:00 -0400

Readers are becoming increasingly rare. I “met” one recently through a second-hand book.

Years ago now, I bought a 86-page specialty instructional book in the consignment section of a specialty shop. For less than half the price of a new copy.

I still haven’t read it but, today, I set down to make the book ready for me to read. Does that sound pompous? I just mean that I was erasing the pencil marks that the previous reader left in it.

Questioning assumptions

doug@dougcuff.name (Douglas Cuff) — Sun, 21 Apr 2024 15:00:00 -0400

Assumptions engage our human emotions.

Some assumptions are embarrassing. CBC Radio “Morningside” host (the late) Peter Gzowski, long in a job that paid more than a living wage, once made the assumption that retirement tax breaks were available to all… when they require a minimum income.
Some assumptions are infuriating. In the “Doonesbury” comic strip, cartoonist Garry Trudeau once did a masterful job of deflating privlege rather than ranting about it. In the daily strip for Wednesday, 19 June 1985, Trudeau has Congresswoman Lacey Davenport attempt to raise awareness of homelessness among rich constituents in Palm Beach, Florida. The heart-cry of one distressed-looking lady is “That’s awful! Why don’t they just move to their country homes?”
Some assumptions are surprising. I grew up in one of the majority of Canadian provinces that celebrate Veteran’s Day, November 11, as a public holiday. When I moved to Ontario, the province that does most of the posturing about honouring our servicemen and servicewomen in the so-called national media, I was taken aback to learn that Ontario does not recognize the holiday. (It merely “observes” it.)

Because assumptions are so closely connected to emotions, you as a technical writer need to be aware that people can get defensive about their assumptions. Part of the defensiveness arises because everyone is unaware of all their assumptions. Being made aware that you have made an assumption can unsettle the ego, regardless of what the assumption was, and unrelated to whether the assumption was valid.

Release notes for smartphone apps

doug@dougcuff.name (Douglas Cuff) — Sun, 07 Apr 2024 10:25:00 -0400

Did you know that there was a time when people actually read release notes? Not all people read them, but some regular customers did.

Since I became an iPhone user, I’ve started noticing the release notes for updated versions of iPhone apps. The only major software publisher that consistly explains what’s new in a release is… Apple itself.

Streamlined in-app notifications informing you when a person joins a collaborative document for the first time

Preserve file format and full quality when adding HEIC photos taken on iPhone or iPad

On iPad, press and hold the Command key on a connected keyboard to select noncontiguous words, sentences, or paragraphs using a trackpad or mouse

It’s not new that the release notes are an afterthought. Too often, they are written by the developer who has been given the responsibility for actually submitting the software for distribution.

Why no blog updates for over a year

doug@dougcuff.name (Douglas Cuff) — Thu, 04 Apr 2024 10:56:15 -0400

I haven’t been posting. Why? Because I ran into a technical issue that prevented me from connecting to GitHub. Weekend after weekend, I tried to solve it.

I read post after post that claimed to have the fix. None of them helped. I have decent technical skills, but I could not find a fix.

Eventually, I accepted that I was going to have to uninstall (part of) a commercial piece of software. It still took a couple of weeks that get that completely erased from my system.

On dropping a stone down a well

doug@dougcuff.name (Douglas Cuff) — Tue, 14 Feb 2023 07:00:00 -0400

The most recent time I was considering and being considered for a new technical writing position, I got a surprise. One of the managers mentioned my recent posting on this blog, Technical writers are not helicopters.

That was the first indication I had had that anyone ever read any of this blog.

Even in the smartphone age, writing is still like dropping a stone in a well and waiting to hear the splash. In fact, writing into the void has become more prevalent, at least in terms of the number of people “publishing,” which can mean that fewer people are reading.

Technical writers are not helicopters

doug@dougcuff.name (Douglas Cuff) — Thu, 08 Dec 2022 10:56:14 -0400

The majority of developers and their managers have absolutely no idea what technical writers do. Most developers think of us as old-school secretaries (administrative assistants) who correct their typographical errors and handle their typing. If you are a developer who knows better, please educate your peers rather than sending me a note with the message “not all developers.”

Developers frequently work with time pressure. They have limited time to code and debug a feature. Why should technical writers not have the same stresses?

Giving thanks

doug@dougcuff.name (Douglas Cuff) — Sat, 08 Oct 2022 10:56:14 -0400

Over the years, I have been blessed by working with terrific people.

Testers. Managers. Developers. Software architects. Customer support people at various levels. Fellow technical writers. Executives. Subject matter experts.

Quite a lot of these people could write a lot better than they thought they could. When they wrote, they thought about the user.

Some of them couldn’t write well but they were great at talking about what they wanted to write… if only I could get enough of their time to interview them. Below-average writers, but still way better-than-average communicators.

Feeling appreciated

doug@dougcuff.name (Douglas Cuff) — Tue, 27 Sep 2022 07:00:00 -0400

While walking through my local park, I ran into a former co-worker from 20 years back. I had been creating documentation; he had been supporting customers. He mentioned to me, 20 years later, how helpful my documentation had been for him.

I do strive to write clearly for both users who need a quick refresher and those who are approaching the product for the first time, so I wasn’t completely taken aback by his praise. But in all the time I had worked for that firm, my co-workers rarely if ever mentioned that they, too, found the documentation helpful.

Break's over

doug@dougcuff.name (Douglas Cuff) — Thu, 22 Sep 2022 07:00:00 -0400

I finally took some vacation, which explains why I haven’t updated the blog recently.

I looked at this blog in a new light upon my return. My tone was getting negative. It’s time to fix that. Apparently, I was more tired than I realized.

Let’s look at an example of good packaging:

Hiring process gaffe

doug@dougcuff.name (Douglas Cuff) — Mon, 29 Aug 2022 12:05:00 -0400

I once submitted an application to a firm that specializes in computer security, and was granted a screening teleconference with a technical recruiter. I was told to expect an e-mail about progress of my consideration for the position on the following Tuesday, which e-mail never arrived. I sent the technical recruiter an e-mail to ask about progress, and got an excuse. Five days later, I got an e-mail from the recruiter which stated that the firm had “decided to move forward with other candidates at this time.”

Naming for the future

doug@dougcuff.name (Douglas Cuff) — Mon, 22 Aug 2022 12:30:00 -0400

How we ended up here: There is never enough time.

Software evolves over time. Example: When writing the software, a developer creates a simple object and calls it Provider. Later, there’s a need for another object quite similar to Provider, so the harried developer takes most (but not all) of the attributes of the object Provider and creates a class (which contains the original object). Which class the developer also calls Provider. There’s no time to think of another name, and even if there were all the time in the world, the developer might not see a need to apply a better name.

On not telling everything you know

doug@dougcuff.name (Douglas Cuff) — Mon, 15 Aug 2022 12:30:00 -0400

Do we, as technical writers, tell the reader everything we know? Do we heck!

We most emphatically do not. And listing just the reasons why we do not would take a long time and a lot of words. That’s listing the reasons, not explaining any of them. But let’s talk about one of the reasons.

Readers are busy people. If they read the documentation at all, it’s usually because they were using the product to get something done, and hit a roadblock. They want to read just long enough to get unblocked.

Writing-sample ethics

doug@dougcuff.name (Douglas Cuff) — Mon, 08 Aug 2022 12:30:00 -0400

Technical writers maintain samples of documents that they once created and add those sample documents to their professional portfolios. Even though I do not (repeat: not) have a portfolio for the sole purpose of employment, writing samples can be useful when seeking a new technical writing position.

Showing samples to prospective employers was always a grey area ethically. What we think of as samples are single copies of work to which we do not own the copyright. But allowing a prospective employer to examine these samples as part of an interview process is not worth anyone “lawyering up” over, especially since we as writers used to control access to the samples and since the duration of that access of yesteryear was enough for a quick perusal but not for any activity that would damage the copyright owner.

Are technical writers 'slow'?

doug@dougcuff.name (Douglas Cuff) — Mon, 01 Aug 2022 12:30:00 -0400

I spend most of my time at work thinking about the product users. Those are the people who will be reading what I wrote. That means I spend a lot of time considering what each person might not know, and might not know they don’t know. Part of the job of a technical writer is helping people learn. Which puts me in a very different head space than a lot of the people I work with.

Hiring process subtext and oblique signals: what's in a form?

doug@dougcuff.name (Douglas Cuff) — Mon, 25 Jul 2022 12:30:00 -0400

I’m happy with my current employer, but next time it comes to looking for work as a technical writer, I intend to remember that not all companies are created equal. Some companies signal to prospective employees how they can expect to be treated. Unsurprisingly, especially to adherents of Sturgeon’s law, more companies will signal that they will not treat you well, but do not despair. There are still companies that signal the significant respect that they have for their employees and prospective employees. These are profitable and respected companies, capitalism apologists please note.

In praise of the accuracy of subject matter experts

doug@dougcuff.name (Douglas Cuff) — Tue, 19 Jul 2022 17:00:00 -0400

During the course of a career lasting over 20 years, would you care to guess how many times I have been given data from a software developer that later turned out not to be correct?

A maximum of three.

Once, another developer informed me that something I had written wasn’t true. I provided the developer with a copy of the e-mail in which a different developer had said it was true. (No, I didn’t rat out the original developer by providing their name.) The developer demonstrated to me that it could not possibly be true. So I changed the docs.

Five duties of a technical writer

doug@dougcuff.name (Douglas Cuff) — Tue, 19 Jul 2022 09:15:00 -0400

Writing requires that you try to reach your reader. Technical writing doubly so. And that’s the part that isn’t easy. There are obstacles, and you have to do the work of overcoming all of them all of the time. Simultaneously.

Here are five of my rules for technical writers.

You have to understand your topic.

In a lot of life, in conversations and in writing, you can have a vague idea of how something works. (For example, you can put gasoline in a car without understanding how the gas fuels an engine.) That’s not true in technical writing. You cannot explain what you do not understand. You have to know exactly what the ideas are, and what all the words mean. Although you don’t have time to become a subject matter expert in everything you write about, you must invest the time and brain-strain to become a student of the subject. And you must resist the seductive pleadings from non-writers to just clean up the writing of someone who does understand the topic. You’re not there to give a polish to writing that you do not understand. You’re there to explain. You have to take that commitment seriously.

Everyone knows THAT!

doug@dougcuff.name (Douglas Cuff) — Mon, 11 Jul 2022 12:15:00 -0400

Development can be incredibly self-focussed. Development managers and developers share information with members of the development team, and can be positively stunned to learn that not everyone outside the team has access.

Nowhere is this more obvious than when development is complete.

There is a belief that the development deadline is available to technical writers, and in my experience, it is not available more than 50% of the time.
There is a stronger belief that the availability of a feature to product users is known to everyone once development is complete. That has enormous impact on technical writers because:
- Technical writers sometimes must wait for confirmation that the product’s functionality is available before taking the step that makes documentation visible to customers.
- Technical writers sometimes do not have access to the product that users do, and cannot check whether the functionality has been made available.

I sympathize with you if you want to believe, “Well, those are just companies that communicate poorly.” That may be so. But they are still the vast majority of companies, and I lose sympathy with you if you want to argue that they are a minority.

Allow me to introduce myself

doug@dougcuff.name (Douglas Cuff) — Mon, 11 Jul 2022 12:14:00 -0400

I’m a technical writer with a career of 20 years’ experience in full-time documentation of software (and occasionally hardware).

When I was doing my undergraduate degree in English, I took a creative writing course. Each week, we had the assignment of writing in a different style, and it was always most enjoyable. The week that we had to demonstrate our skill in instructional writing, I took advantage of my natural aptitude for detail and wrote a procedure for making a photographic print using a film negative and an enlarger. I got great marks for that assignment. (Historical note: We were still a long way from using digital cameras, so film negatives were still very much a thing.) I wrote with precision and clarity.

About Doug

doug@dougcuff.name (Douglas Cuff) — Mon, 01 Jan 0001 00:00:00 +0000

I’ve been writing documentation and help for over 20 years. It’s still fun. Sometimes people unwittingly make it less fun. I write about all that here.

me

If you insist… some actual professional autobiography (my first post here).

the technology

This site was generated by Hugo using the beautifulhugo theme.