Monthly Archives: June 2014

Docs that are Part of Larger Systems

It is easy to think of documentation as simply the reader’s companion, which they use when they need help with a product or service. But a lot of documentation is more than this, it is part of an industrial or institutional system. Designing and writing documentation to be part of such a system can be… Read More »

The Reader’s Path Cannot be Made Straight

The straight path. It is an idea with immense psychological appeal to us. Every valley, Isaiah promises, shall be exalted, and every mountain and hill laid low (Isaiah 40:4). As communicators, we naturally want to lay out a straight path for our readers. But the truth is, we lack the power to make the crooked straight… Read More »

Structured Writing is Essential for Developer Docs

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 »