XML sucks. Don’t get me wrong. All kinds of really valuable and important systems use XML to perform vital functions. But performing a vital function does not keep something from sucking. Lots of people think Windows sucks, but it performs a vital function, and lots of people use it because of that. In fact, performing a vital… Read More »
In a recent LinkedIn discussion on “Most important competencies for technical writers,” I commented that the most important skill for technical writers was explanation, and that the ability to write and the ability to explain are not the same thing, and that the ability to explain is significantly less common that the ability to write… Read More »
It is easy to think of metadata as a few information fields that you tack onto an article when you submit it to a CMS. In this vision, metadata is something fairly small, a triviality in comparison to the content itself. The reality is just the opposite; for any piece of content or data, the… Read More »
When I started my career in tech writing, it was the age of the writer. Tech writers tended to work independently on a single book for months at a time. Better, for many, they not only got to write the book, they got to design it and shepherd it through the publication process. At the… Read More »
Following my recent STC Webinar on Every Page is Page One, an attendee wrote to ask about the discipline of linking. Unfortunately, that email mysteriously vanished from my inbox before I could answer personally, so, whoever asked, I hope you see the answer here. Linking is important to Every Page is Page One and to a bottom-up… Read More »
I am very grateful to Jonatan Lundin for a lengthy conversation on the subject of topic patterns because it helped me to crystalize something important about the basis for the principles of EPPO information design and how they are derived. Approaches based on psychology Traditionally, theories of information design have been psychologically based. Researchers (usually… Read More »
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… Read More »
I was reading JoAnn Hackos article on easy DITA authoring solutions and it got me thinking about what the word “easy” means in regard to DITA or any similarly complex technology. Can an editing interface make DITA easy? Some DITA consultants that I know complain bitterly about tools that make that claim. DITA may be many… Read More »
Transclusion is pulling content dynamically from one page into another page. Rather than cutting and pasting text from one page to another, you create a pointer to the page you are borrowing from. That pointer is resolved at run time, pulling content from the other page when your page is loaded. Transclusion was a fundamental part of Ted… Read More »
Tom Johnson wrote a post recently in which he questioned the value of structured writing for developer documentation. Needless to say, I disagree. But Tom and I are not really at odds here. Rather, he means something different by “structured writing” than I do. Structured writing is about content quality, not publishing What I mean… Read More »