Structured Writing FOR the Web

  By Mark Baker | May 17, 2013 - 2:25 pm | , , ,
8 Comments

Tom Johnson started the discussion with  Structured authoring versus the web. Sarah Sarah O’Keefe and Alan Pringle took it up in Structured authoring AND the Web. My turn: Structured authoring FOR the Web.

One of my long term grievances is that structured authoring has been adopted piecemeal. Rather than approaching it holistically as a method that can provide a wide range of quality and efficiency benefits to the authoring process, people have tended to adopt it for a single purpose, and to use it only to the extent that it achieved that singular purpose.

(more…)

Fewer People Read Longer Topics, and that’s Okay

  By Mark Baker | May 13, 2013 - 9:30 am | ,
2 Comments

Fewer people read longer topics. But it’s not something to lose sleep over, and certainly not something to shorten topics over.

Tom Johnson has a recent  series of posts on topic length (Does DITA Encourage Authors to Fragment Information into a Million Little Pieces?, Do Short Topics Make Information More Findable?, and Why Long Topics Are Better for the User). The discussion around these posts dwells, as all such discussions seem to do, on the question of whether fewer people will read longer posts/topics/articles/etc.

I believe this concern is misplaced. Here’s why.

(more…)

Book Outline — Every Page is Page One

  By Mark Baker | May 2, 2013 - 12:23 am |
45 Comments

As I announced a while back, I am working on a book called Every Page is Page One: Topic-based Writing for Technical Communication and the Web. The book is in pretty good shape at this point, so I wanted to share the outline with you to see if you have any feedback that I can incorporate before the last i is dotted and the last t is crossed.

As an added incentive, XML Press will present a free copy to one person, selected at random, who comments on this post. (more…)

The Web Leaves You Smarter, But Feeling Dumber

  By Mark Baker | April 29, 2013 - 9:57 am | ,
15 Comments

Is the Web making us smarter or dumber? Kath McNiff sums up the dilemma beautifully:

I fear that the web is not making me smarter. It’s distressing my synapses and dumbing me down. Not because the content is junk but because there is too much good stuff. Amazing material at my finger tips – TED talks, zeitgeisty blogs, beautiful pins and seriously meaty journal articles.

It’s the “too much good stuff” that is the problem. (The emphasis is Kath’s, not mine.) Feeling smart is not so much about having knowledge, as it is about feeling like you are in command of a subject. Read a book and you can really feel like you understand the subject matter. You feel smart. (more…)

The Key to Organizing Web Content is Stickiness

  By Mark Baker | April 22, 2013 - 10:20 am | ,
8 Comments
Sticky bun.

The stickiest content rises to the top. Image courtesy of Maggie Smith / FreeDigitalPhotos.net

The most important thing you can do to organize your Web content so that people can find it is to make it sticky. Making it sticky is more important than categorizing it or placing it in a hierarchy or taxonomy. It is even more important than linking your content set effectively. In fact, if you don’t make it sticky, neither of those other things are likely to matter much.

It is easy to think of the Web as simply a vast ocean of content. But if it were that, it would not work at all. What the Web actually is is a vast index of content. It is not a fixed index, like in a book, but a complex, dynamic, volatile, multi-stream index. For purposes of findability, how your content is organized on the Web comes down to how it appears in that index. And while you can definitely contribute to how it is indexed in small ways, its indexing is largely controlled by others. The Web organizes itself communally. (more…)

Solve First, Buy Afterwards

  By Mark Baker | April 15, 2013 - 10:28 am | ,
4 Comments

In, This Is Why It Matters if Your User Guide Is Just an Afterthought, Bill Kerschbaum posits a scenario in which a potential customer, impressed by your glossy website, downloads a trial version of your software, is initially impressed, but then tries to figure out how to do something, is disappointed by the poor user manual and decides not to buy the full version.

My immediate thought on this was, but that is not what happens today. People don’t turn first to the user manual. The first thing they do is Google or ask their social network how to do something. Unless your user manual is online (preferably in the form of Every Page is Page One topics), and unless it ranks reasonably well in the search results for questions about your software, it isn’t even going to get a chance to disappoint. Instead, whether the user decides to buy your software or not is likely to depend on whether some other user has documented how they did the particular task they are interested in.

In other words: its a Google-first, manual-later-maybe-never world. (more…)

The Value of Collegiality in Technical Communicaiton

  By Mark Baker | April 8, 2013 - 11:29 am | , ,
15 Comments

Society’s attitudes towards written communication are changing. This is not simply a matter of the eternal development of language, though that, of course, goes on, and at an accelerated pace in any time of great social or economic change. There is also a difference in the relationship between the writer and the reader.

We might easily dismiss this as simply becoming “less formal” — a development you will either welcome or disdain according to your taste. And we might also too easily see as growing informality what is really just the diurnal migration of vocabulary. I would suggest that what is happening is something more precise and more important than that: the relationship between writer and reader is becoming more collegial.

(more…)

Sometimes, Readers Do Classify their Experience

  By Mark Baker | April 2, 2013 - 8:40 pm | ,
6 Comments

In my last post I argued that navigation based on classification schemes does not work because readers don’t classify their experiences. But while that is generally true, it is important to note that sometimes readers do classify their experiences, and that when they do, it is important that we base our navigation on those classifications.

(more…)

Readers Don’t Classify their Experience

  By Mark Baker | March 25, 2013 - 3:26 pm | , ,
15 Comments

In Web Organization is not Like Book Organization, I said that the TOC does not work at a large scale. It is worth talking a little more about why it doesn’t work, because it has important consequences for many of the navigational schemes that people propose for the Web and other large information systems.

The reason a TOC does not work at a large scale is that a small scale TOC acts as a list that the reader can simply browse, but a large scale one becomes a classification scheme that users have to navigate. If you can’t take the TOC in at a glance, or at least read it through comfortably, then you have to trace down particular paths in the hierarchy of the TOC, and that means you have to figure out the classification scheme behind the TOC. And that does not work.

The reason it does not work is that people do not classify their experience. They do not say, “I have an ache in my second upper bicuspid,” they say, “I have a toothache.”

(more…)

Web Organization is not Like Book Organization

  By Mark Baker | March 19, 2013 - 10:46 am | , ,
11 Comments

One of the most difficult aspects of moving content to the Web is that webs are not organized like other things — books in particular. And the difference is not small. It is not that web organization is somewhat different from book organization. It is so different that you can’t even look at web organization the way you look at book organization.

And that may be the biggest problem in moving content to the Web. We are used to being able to look at the organization of our content in a particular way, from the top down, and that does not work on the Web. That makes the difference very difficult to get used to.

(more…)