Mark Baker

Baby It’s Scold Outside

The latest target of the scolding classes is a Baby It’s Cold Outside, a pop song from the 30s that is suddenly being “banned” from radio stations on the grounds that it condones rape, and, specifically, that the line “What’s in this drink?” is a reference to a date rape drug.

The accusation is absurd. As this article explains, the song is actually about the woman trying to talk herself into staying the night in the face of a list of a social taboos against her doing so, and “What’s in this drink?” is a common trope of the pop culture of its time, used to excuse saying something that violates some social norm. You are blaming your words on the booze, in other words, and the joke is that there is usually nothing in the drink. read more

Designing for Feedback

We were discussing the biggest challenges in Tech Comm at the last STC Toronto brunch and we all seemed to agree that the difficulty getting feedback on the effectiveness of the content we create is the biggest challenge. The things that really matter in technical communication is whether users can achieve their goals after finding and reading the docs, and whether that makes a difference in whether they buy from you again or speak well of you to their friends and colleagues. These things are incredibly difficult to measure. You are just not there to see them happen, and it is very difficult to separate their effects from the effects of the work that designers, developers, sales people, trainers, field engineers, and support staff do.

Because we have such a hard time getting that feedback, it is particularly important that we get intermediate feedback: feedback on things like accuracy, consistency, coverage, relevance, and appropriate use of language and examples, which we know, on general principle at least, correlate well with customer success. Yet we do not tend to design our documentation systems and processes to generate such feedback.

It is well established that there is a direct relationship between the speed and accuracy of feedback and quality. The more feedback you get and the more promptly you get it, the better work you will do. But tech comm has traditionally relied almost entirely on human feedback from editors, and reviewers.

But human feedback of this sort has two problems. First, it is slow. You might work for weeks on your content before it is submitted for review or editing. Second, human feedback comes with emotions attached.

We had an interesting discussion on Larry Kunz’s blog about the perils of giving feedback to colleagues. Referring to Liane Davey’s post on giving feedback, Larry talks about the need to be ready to receive feedback, as well as needing to be ready to give it professionally. From a psychological point of view this makes complete sense. The problem is, it means feedback will often be delayed, in order that both parties be in the right frame of mind, and delayed feedback means quality and productivity both suffer.

I suggested in that discussion that we should make a distinction between feedback and coaching. Feedback is a necessary part of work. Feedback tells you if what you are doing is working. It can’t be delayed without cost. Coaching is a part of career development. It is used just as much to make the good better as to make the bad acceptable. But it is not apt to be effective unless both parties are in the right frame of mind.

This distinction is clear enough on paper (or whatever should replace that expression today — clear enough in pixels???), but if the only vehicle you have for giving feedback is human to human, how is the emotional impact any different between feedback and coaching?

Mechanical forms of feedback come without judgment or emotion. We can be frustrated by a machine, even humbled by a machine, but we are never embarrassed by a machine. We don’t feel the machine’s pity or contempt. We do not feel that we have sunk in the estimation of the machine. We can accept mechanical feedback with far more equanimity than we accept human feedback.

Equally importantly, we don’t have to wait for the machine to be finished its own work or have some free time in its schedule before it gives us its feedback. We don’t have to do a bunch more work before we get the feedback on our first piece of work. The work will be fresh in our minds when we get the feedback, and whatever lessons it teaches us we can apply to the work we do next.

Finally, the machine is not flustered or annoyed by our request for feedback. It is not anxious to get back to its own work. It is not bored with the task of giving feedback. It is not jealous of us. It did not wake up on the wrong side of the bed this morning. It’s car is not in the shop, its basement is not flooded, and it did not have a fight with its spouse this morning. It has not forgotten all about the code it wrote three months ago. It does not think its job is to be the grammar police. Nor does it think your documentation should be a paean to the brilliance of its design work.

One of the great advantages of structured writing is that it allows us to build mechanical feedback loops into the content development process. It allows us to develop strict topic types the define exactly what information is required on a particular subject. It allows us to verify information between different documents and between documents and external sources. It also allows us to factor out a lot of the petty mechanical things that writers can get wrong so that we don’t have to bug them with feedback about them, which can give them more time to focus on the more important feedback.

If we can take the human element out of all the kinds of feedback that can be generated mechanically, we not only ensure that that feedback is more complete, more accurate, and more timely than human feedback could possibly be, we may also leave both the giver and receiver of coaching more receptive to it, and allow it to focus on the parts of performance that cannot be judged mechanically.

The Death of Hierarchy

Hierarchy as a form of content organization is dying. A major milestone — I want to say tombstone — in its demise is the shutdown of the Yahoo directory, which will occur at the end of the year according to an article in Ars Technica, Yahoo killing off Yahoo after 20 years of hierarchical organization. (Actually it seems to be offline already.)

As the article observes, a hierarchical directory made some sense when Yahoo was created:

In the early days of the Web, these categorized, human-curated Web listings were all the rage. Search engines existed, but rapidly became notorious for their poor result quality. On a Web that was substantially smaller than the one we enjoy today, directories were a useful alternative way of finding sites of interest. read more

Designing topic types

A number of readers have asked me to write about how to design a topic type. Although it can sound complicated, especially if your bring XML schema definitions into the mix, designing a topic type is actually pretty simple.

Before we begin, though, set aside all the issues around XML. XML has nothing to do with topic type design. It may have a lot to do with how you implement your topic types (or nothing to do with it), but it has nothing to do with how you design them.

Needed information in a specific form

A topic type is essentially two things:

A list of the pieces of information a reader needs to accomplish a particular purpose.

A standard form and order for presenting that information.

Don’t just try to fit into development’s agile process. Create your own lean content development process.

Technical writers are increasingly finding themselves involved in the agile process of the development organization. The most common way this happens is that a writer gets assigned to the team for a sprint and is expected to produce documentation in the same sprint as the developers produce the feature.

This has one huge plus for writers: development cannot declare the sprint complete until the documentation is done. This means that it is in the interest of every developer to help ensure that the tech writer has what they need to get their work done. Given that getting information when needed is a major issue for many tech writers, this can be a very big win.

But there are plenty of downsides to this arrangement as well. Some of the more common complaints include:

There are often not enough writers available to assign one writer to each sprint team full time, so the writer ends up being assigned to several teams. Attending multiple scrum meetings can then take up a big chunk of the day, and juggling the priorities of multiple teams becomes a significant headache. Also, having to switch gears between different features can inhibit the writer’s flow, greatly increasing the time it takes to write the content.

It does not always take the same amount of writing time to document a feature as coding time to implement it. Some features that have major architectural impact but little user-visible behavior can take weeks to code while requiring little or no documentation. Small changes to user-visible parts of the system, on the other hand, may require major documentation effort while being implemented with very little code. The writer trying to work in concert with the sprint team may be scrambling one week and twiddling their thumbs the next.

Documentation is at the mercy of development’s process and schedule, which is not being optimized for the creation of documentation, but of software. And, of course, not every organization implements agile well. Being at the mercy of a good process designed for something else is not ideal. Being at the mercy of a bad process designed to produce something else is very difficult.

Tying all docs development to software development sprints may encourage product oriented rather than task oriented or user oriented documentation. Petko Mikhailov makes this point in a post on LinkedIn where he notes:

Author: Mark Baker