The War Between Content Management and Hypertext

Summary: As content consumers, we love hypertext. As content creators, we still believe in content management, even after years of disappointment. Content management disappoints because it does not scale for culture. It is time to embrace hypertext instead.

I should know better. Every time I put the word “hypertext” in the title of a post, my readership numbers plummet. Hopefully “content management” will help pull them up this time, because as content professionals we need to come to terms with hypertext. read more

Structured vs Unstructured Hypertexts

One of the questions I am often asked about Every Page is Page One is whether it simply means write articles instead of books. But while articles are certainly much closer to the EPPO model than books, there is something more to EPPO than simply writing articles. EPPO is also about the relationships between articles/topics/pages (or whatever else we decide to call them).

A single article is seldom sufficient to cover a large subject. You often need to create a much larger content set, consisting of many articles/topics/pages, to cover a subject adequately and to meet your audience’s varied needs. In the age of the Web, however, in the age of Google and information foraging, a linear or hierarchical organization of content is no longer adequate, and does not match how modern readers approach content. We need another way to approach the organization of content — one I have termed bottom-up information architecture. read more

Topic Patterns vs. Topic Types

One of the principles of Every Page is Page One information design is that an EPPO topic conforms to a type. But I have come to think that that formulation is not quite right. It should really be, an Every Page is Page One topic conforms to a topic pattern.

The difference between type and pattern

What is the difference between a topic type and a topic pattern? In structured writing terms, a topic type, or, more generally, a document type, is a formal set of rules about the structure of a topic which is capable of being expressed by a schema. In most cases, that means an XML schema or something similar. This usage is consistent with the use of the word “type” in other computing applications. A type is a data definition. read more

Content is a Utility

Summary: When content is a utility the job of the tech writer is to ensure reliability of supply.

In my earlier post, Content as Furniture, I suggested that while content used to be furniture — something to be acquired selectively and displayed as a prized possession (and a mark of status) — it is rapidly becoming a utility — something we simply expect to be there when we need it, like water or electricity.

The notion that content is becoming a utility has some pretty important consequences that I think are worth discussing. read more

Changing the “what” in WYSIWYG

The “what” in “what you see is what you get” is not always “formatting”.

Authors need WYSIWYG (What You See is What You Get) displays to work effectively. This is basic ergonomics. If you can’t see the thing you are supposed to be creating, you will have a hard time creating it well.

But while authors always need WYSIWYG displays, the “what” that they need to see is not the same thing in every case. There can be several different values for the “what” in WYSIWYG.

The term WYSIWYG was coined to describe the displays of word processing and desktop publishing programs. In this case, the “what” was the formatting of the printed document. (At the time we were talking strictly about printing on paper. The “what” you saw on screen was the “what” that was going to appear on paper — more or less.)

This was a big step forward, but the step forward was not enabling people to do typesetting with computers. Doing typesetting with computers had been possible for a long time using a language called TeX, which is still used in some places today. But TeX, has never been widely used because while you can specify formatting with great precision in TeX, you can’t see the formatting that you are specifying as you work. You can only see it afterward when you run the file through the TeX program to create formatted output.

Make a mistake in your TeX markup, and your output may be garbled in ways that make it hard to find your error, and finding and fixing errors can be fiddly and tedious. Desktop publishing was a big step forward because it allowed people to see the formatting they were creating as they created it.

But formatting is not always the “what” in WYSIWYG. In Learning Python, Mark Lutz describes the syntax of the of the Python programming language as WYSIWYG.

Python is a WYSIWYG language — what you see is what you get — because the way code looks is the way it runs, regardless of who coded it.

Lutz, Mark (2013-06-12). Learning Python (p. 326). O’Reilly Media. Kindle Edition.

What he means in this case is that with Python, unlike most other programming languages, the indentation of the source code always shows the logical structure of the program. If formatted poorly, the indentation of code in a C or Java program can be completely misleading as to the actual structure of the code. Lutz provides this example:

if (x)
    if (y) 
        statement1; 
else 
    statement2;

Here the formatting of the code makes it appear as if the else statement belong to the first if statement, but it doesn’t. It actually belongs to the second if statement. The structure you see is not the structure you get. In Python, such confusion cannot occur. Lutz’ Python example looks like this:

if x: 
    if y: 
        statement1 
else: 
    statement2

In this case, the else does belong to the first if, as it appears. If it were indented under the second if, like this:

if x: 
    if y: 
        statement1 
    else: 
        statement2

then the else would belong to the second if statement

In Python, the indentation of the source code determines the structure of the program, and thus the logical structure you see in the source is the actual structure you get in the program. Thus Lutz chooses the term WYSIWYG to describe the language. But in this usage of WYSIWYG, the “what” is not formatting, but structure.

In content engineering there are multiple possible “whats” you might want from a WYSIWYG display. Desktop publishing is based on the premise that the author is also the designer, the typesetter, and the prepress person, so the “what” is formatting. We can be more explicit about this by substituting the word “formatting” for the word “what” in the acronym: FYSIFYG (the Formatting You See Is the Formatting You Get). The desktop publishing approach requires a FYSIFYG display.

Before the days of desktop publishing, when authors were only required to worry about the text, and did not have to wear a dozen other hats, they got by with pens or with typewriters. Both these tools had a TYSITYG display: the Text You See Is the Text You Get.

Today, however, the increasing demand for malleable and repurposable content means neither TYSITYG not FYSIFYG will suffice. We need more than just the text, and something other than text plus formatting. We need structure. What we need to create structured content, therefore, is a SYSISUG display: the Structure You See Is the Structure You Get. Creating such a display, alas, has not been easy.

It might seem like a raw XML file is a SYSISUG display, because all the structure is there in the XML tags. Many XML editors that let you switch to a view of the raw XML will call this “the structure view”. The problem is, while the structure is there, it is not in the least easy to view. There is way too much syntactic noise in an XML file for the reader to easily discern the structure it expresses, as this chunk of the DocBook source for my book shows:

<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="chapter.linkrichly"> <title>EPPO Topics Link Richly</title> <indexterm><primary>Weinberger, David</primary><secondary>on linking</secondary> </indexterm> <blockquote> <attribution>David Weinberger, <citetitle pubwork="book">Too big to know</citetitle> <biblioref linkend="TooBigToKnow"/></attribution> <para><indexterm class="startofrange" xml:id="idx.linking-1"><primary>linking</primary></indexterm>Links are the visible manifestation of the author giving up any claim to completeness or even sufficiency; links invite the reader to browse the network in which the work is enmeshed, an acknowledgement that thinking is something that we do together.</para> </blockquote> read more