Affordances are relative

Affordances, those features of a product that help you figure out how to use it, are relative.

Most of the busses in the Kitchener-Waterloo region have rear doors that open when you wave your hand in front of them. The one I took downtown this morning must have been an older model because it just had two vertical push bars on the doors.

When we arrived at the terminal, the young woman at the front of the queue to get off started to wave her hands in front of the door, which did not respond. Puzzled and alarmed, she began to shout at the driver to open the doors, until someone behind her said, “push the handle”. read more

Why we need constrainable lightweight markup languages

This post is in response to a Twitter conversation that started with:

This led to a discussion about extensibility and constraints in markup languages. Markdown is a pretty simple lightweight markup language (and popular for that reason) but it is what it is. You can’t add anything to it except by creating your own variant by modifying its code (which lots of people have done). read more

Can Content be Engineered; Can Writers be Certified?

tl;dr: We can apply engineering methods to content development, but we do not have the body of proven algorithms or known-good data to justify formal certification of communication professionals they way we have for doctors and engineers.

We talk about content engineering. I call myself a content engineer sometimes. But can content really be engineered? Is content engineering engineering in the same way that engineering a bridge is engineering, or only engineering by analogy?

This post is prompted by a fascinating conversation with Rob Hanna and others at the monthly STC Toronto Networking Lunch. The conversation morphed into something I think I can fairly characterize as: is there a uniform methodology to technical communication, one that can form the basis of a curriculum, a certification, or a toolset, or is there a legitimate diversity of approaches, roles, methods, and tools. read more

Writing Excellence Through Domain Awareness

A little while back, Tom Johnson posted an article entitled Seeing things from the perspective of a learner in which he says, “The balance between knowing and not knowing is the tension that undergirds the whole profession of technical writing.”.

I think that is absolutely correct. The point, after all, is to assist the reader on their journey from ignorance to knowledge. I say assist, because this is not a journey that can be accomplished simply be reading. The reader has work to do to integrate their knowledge. They need to get their hands dirty. But a sympathy with the troubles and perils of that path is at very least, highly useful to the writer. read more

What is an “Expert Writer”?

“Hire Expert Writers,” Says Google

That is the title of a post from M2Bespoke about Google’s emphasis on returning reputable content. What is an “expert writer” in this context?

Many of those who have commented on it and passed it around take it to mean expertise in writing. That seems to be the interpretation that the author of the article is making as well:

There’s no doubt you’re experts in your industry, but do you have professional writers within your business to convey that expertise? Google says: if not, why not? read more

Why does XML suck?

XML sucks. Don’t get me wrong. All kinds of really valuable and important systems use XML to perform vital functions. But performing a vital function does not keep something from sucking. Lots of people think Windows sucks, but it performs a vital function, and lots of people use it because of that. In fact, performing a vital function is what keeps sucky things around. If they perform a vital function, they are hard to get rid of, despite the fact that they suck.

Not that that prevents people from trying to work around them. read more

One Answer, Many Questions

It is often appealing to think of technical communication as a process of answering user’s questions. The difficulty with this view is that one answer can have many questions. If you answer each of those questions, you would be providing substantially the same answer over and over again.

This is very easy to see on StackOverflow, a question and answer site for programmers. Privileged user of StackOverflow can mark a question as a duplicate of another question. Here’s an example:

A question marked duplicate on StackOverflow.

The question here is “How to check if a variable is a dictionary in python”. This is a question that programmers are going to ask themselves many times. It is a specific instance of a more general question, which is, “how do you check if a variable is of a specific type in Python?” read more

The Difference Between Story and Drama

In our data-driven age, we tend to give short shrift to story. Story tends to get herded off into the ghetto of drama. Story is for amusement; at work we stick to data.

When I wrote my last post, suggesting a switch of terminology from “content” to “story”, many people naturally interpreted story as meaning drama. As Larry Kunz put it, “In technical writing, the story’s hero is your reader, who’s trying to accomplish something or learn something.”

That may be a useful way to think about your tech writing, but it is a definition of story derived from the world of drama. When I talk about story in the world of tech comm (or marketing communication, for the most part) I am not talking about drama, I am talking about general human communication about everything. Because story is not a special preserve of entertainment. It is how we communicate about everything. read more

Let’s Replace “Content” with “Story”

We used to be in the writing business. Then we were in the communication business. Now we are in the content business. It’s probably getting time to change the monika again. I have a candidate: “story.”

There have always been two schools of thought about the word “content”. Some love it. Some hate it.

I hate it. It is an ugly generic word chosen specifically not to mean anything specific. We can’t say “writing” because sometimes we use pictures. Etc. Etc. It is the sort of word you use when you don’t care what is in the container. (Many years ago I asked a Documentum rep what Documentum meant by content, to which he replied, “anything you can store in Documentum.”) read more

Is There a Reproducible Method for Explanation?

In a recent LinkedIn discussion on “Most important competencies for technical writers“, I commented that the most important skill for technical writers was explanation, and that the ability to write and the ability to explain are not the same thing, and that the ability to explain is significantly less common that the ability to write well enough.

This scarcity of natural ability to explain well, I argued, is why we need to pay attention to tools and structure, because we need to find ways to help people who do not have a natural gift for explanation to explain things at least reasonably well. Tacitly, this argument suggests that there is a reproducible method for explaining things. read more