EPPO Topics Conform to a Type

One of the more unexpected characteristics of Every Page is Page One topics, is that they tend to conform to a type. We tend to think of topic typing as something specific to structured writing, something that is not natural to how we write, but something that is imposed on content for the sake of making it available for reuse, of for some other purpose.

But if we look at the millions of Every Page is Page One topics that exist everywhere across the web, we find that an very large number of them actually show strong characteristics of topic typing. Conforming to a type is actually something that comes naturally to an Every Page is Page One topic. read more

Trust is Essential to Creating Great Docs

My good friend Pamela Clark asks me to comment on

what product development organizations, processes, and structures best support great user-oriented documentation

I’ve commented over on Tom Johnson’s blog that tech pubs organizations tend to make a slow migration through the corporate landscape, and that I believe that the best home for pubs is in the development organization. But I also believe that tech pubs success is all about relationships, and there is more to that than simply the reporting relationship. In the end, if you want to create the conditions to do great work in tech pubs, you have to be valued. read more

Technical Communication is Not a Commodity

The latest attempt by the STC to promote a certification program for technical communications prompts the thought that technical communication is not a commodity.

What does it mean to say that a profession is, or is not, a commodity? A commodity is any good which will provide the same quality and performance no matter which supplier you buy it from. Gasoline is a commodity. Sugar is a commodity. No matter which brand you buy, your car will run just as well and your tea will taste just as sweet.

A profession is a commodity if you will receive substantially the same service no matter which member of the profession you use. Accounting is a commodity. Your books should be substantially the same no matter which accountant prepares them. Technical writing is not like that. Ask two technical writers to write something on the same topic, and the results are apt to be substantially different. read more

The Best Place to Find a Needle is a Haystack

HaystacksConventional wisdom tells us that the best place for a needle is in a needle case, and the best place for hay is in a haystack. If you want to find something, or want other people to find it, you should put it in the right place. As we were all taught: a place for everything, and everything in its place.

That was true when we lived in the physical world. But we don’t live in the physical world anymore. We live on the Internet, and the Internet is topsy turvey world in which the best place to find a needle is actually a haystack. read more

The Purpose of All Communication is to Change Behavior

One of the quickest ways I have found to help someone who is struggling to formulate a message is to remind them that the purpose of all communication is to change behavior. If you put the message out into the world, and no one’s behavior changes as a result, then your message has clearly failed. Thinking about your message as a means of changing someone’s behavior does wonders to clarify the task. You really only need to answer three questions:

  • Whose behavior am I trying to change?
  • How do I want them to behave?
  • What can I say to them that will motivate them to behave this way?

If you can’t answer the first two questions, you are not ready to begin. If you can answer the third, you know exactly what you have to do to succeed. I have found this simple mantra to be a very powerful tool for focusing people on how to create a successful message. read more

Characteristics of EPPO Topics: Stay on One Level

One of the less obvious but more important characteristics of an Every Page is Page One topic is that it stays on one level. As with the other characteristics I have discussed in this series, being standalone, having a specific limited purpose, and establishing its context, staying on one level is not an ideal, but a common feature of millions of page-one topics on the web. What makes this characteristic worth pointing out is that it is something a topic does not share with books.

Approximation, Correction, and Tech Comm

Charge of the Light Brigade

Charge of the Light Brigade

At the Battle of Balaclava, an order reached a brigade of light cavalry to take the Russian guns. The general who sent the order was referring to a small artillery position that had been abandoned. But the commander of the light brigade could not see those guns. He could only see the main Russian battery at the end of the valley. He charged, and the light brigade was cut to pieces. The Charge of the Light Brigade can tell us something pretty interesting about the development of technical communication today. read more

Characteristics of EPPO Topics: Establish Context

This post is the third in my series on the characteristics of Every Page is Page One topics, which I introduced in Every Page is Page One Topics are Everywhere, and continued in topics on the properties  standalone and specific limited purpose.

This series is not a attempt at designing something new; it is an investigation into the properties of the millions of page-one topics that already exist, and that are being created everyday. At this point a reader might fairly ask why such a study is necessary, and the simple answer is that while technical writers in large numbers have come to embrace topic-based writing in principle, many still struggle to create topics that really work, and in many cases they quickly retreat to some form of book-like heirarchy of information. read more

Three Components of Writing Skill?

Tom Johnson recently blogged on What Does It Mean to Know How to Write? Protesting the notion that “everyone can write”, Tom proposed a linear scale of increasing writing skill. Lively discussion followed and Ellis Pratt responded with a blog post Assessing writing skills – a response to “What Does It Mean to Know How to Write?” which proposed that writing skills might be plotted on a two dimensional grid. Ever one to jump on a trend, I am going to propose a three dimensional model. No doubt a proposal in four dimensions can’t be far behind, but for now… read more

Characteristics of EPPO topics: specific limited purpose

This post is the second in my series on the characteristics of Every Page is Page One topics, an inquiry into the common characteristics of the millions of page-one topics that already exist. The first post in this series covered the standalone property. This post covers the closely-related property that an page-one topic has a specific limited purpose.

In the previous post, I introduced a distinction between a topic dependency and a reader dependency. A reader dependency is one the reader brings to the material — some wider purpose or some lack of background information or relevant data. A topic dependency is something the topic needs to fulfill its purpose for every reader. In order to tell a reader dependency from a topic dependency, you need to know what the purpose of the topic is. read more