See “Why The World Is Ready For Dexy” and “Dexy and Literate Documentation” as well as the technical writing section section of the tychoish wiki for some background to this post.

Let’s establish some basics. Content, as I think of it, in the context of new/web/digital media, is all of the stuff we read and right on the web. Documentation are those texts which supports the use and creation of technical tools, and explains technical concepts. While obviously read literally, documentation is content, but I think the way we’ve come to understand other kinds of digital content provides an incomplete basis for understanding how technical texts are published and consumed on line.

Consider the following assumptions that we can make about most forms of content on the web:

  • The basic unit of content is pretty short. 1000-1500 tops is the upper boundary for most blog posts and articles, and while some kinds of content can sneak by with slightly longer units--particularly in well structured contexts--these are exceptions.
  • Most content on the web is time-sensitive. While everything gets archived, the focus of publication is often on volume, which increases the chance of producing something that “goes viral” and gets a lot of attention. All other things being equal, the most successful on-line publishers are the ones with the shortest publication processes and the most regular publication cadences. After a short period of time, what’s in the site archives is probably largely irrelevant.
  • Given the way that some content competes with other content, success is often determined by specialization, and the tightness of focus. It’s easier to be the loudest voice in a very small room than it is to be the loudest voice in a large room or a lot of small rooms. Content, thus, needs to be very focused and address very niche interests.

in contrast:

  • Documentation texts tend to be pretty long, and while there are some “quick reference”-scoped texts, and some very complete texts that are quite long, on average documentation is substantially longer than “content.” This means it needs to be produced differently, and we can expect different usage patterns.

  • In general people don’t read documentation. This isn’t just that people don’t “rtfm,” but that if generally people’s interaction with a piece of documentation begins with a specific question or problem. They don’t say “oh, that manual for $xvz product looks interesting, i’ll read it,” and i think the “i should read the documentation for $uvw before i begin doing $task,” is much less common than we’d like to think.

    People read documentation very tactically. So it’s important that documentation exist and be complete, but we should have no illusions that people read any documentation from beginning to end as “clean slates.”

  • Documentation is always already very tightly focused, unlike content. While some technical publishers may publish “second hand documentation,” and thus be able to focus on documenting different aspects of the user experience, most documentation producers must aim to cover as much as possible, and allow users to find and take advantage of whatever information that is most useful for them.

As a result, it’s absolutely crucial that we don’t think of and produce documentation as being crucial. I think treating documentation as something that needs to be compiled. is probably the first step in “doing right” by documentation. Build tools like dexy, similarly, are great because they let writers and developers produce documentation in ways that make sense.

If you write or produce documentation--and better content as well--I’m interested in hear what you think about these issues. Onward and Upward!