Technical Communications Services
Principles
Information development should be guided by the needs of the customer, not the needs of the tools.
Sources
When I first entered the world of online content development in 1999, I was initially guided by my background in literary theory and analysis. My principles derived from Reader-Response theory, in which the meaning of the work is determined by the experience of the reader, as well as the work of Jakob Nielsen at Sun Microsystems, which was the basis for his book Designing Web Usability. As I began working in the industry, I was also introduced to the work of Edward Tufte and John M. Carroll. From all of these influences, I formulated an approach to online content that was reader-centric and focused on meaningful impact - my content is meant to educate, persuade, and move the reader to action.
My approach to information architecture, informed by Carroll as well as Ted Nelson and the Darwin Information Typing Architecture (DITA), is similarly reader-centric. This means putting the needs of the reader first, thinking of what it is they want to accomplish, and making it easy to find the information they need.
Ward Cunningham and Bo Lebouf’s The Wiki Way introduced me to a medium well-suited to the practical implementation of my theoretical principles, and for much of my career I have focused on developing enterprise-scale product information wikis on platforms like Confluence, TWiki, and XWiki, with topic and content structures based on DITA.
With a reader-centric approach to content comes a responsibility to the reader.
Does the content help them complete a task or achieve a goal?
Does it persuade them to connect or take action on their own?
Does it bring them to a greater understanding of a concept or situation?
Defining the desired impact for the reader should always be the first objective of any technical communications project.
From these sources and experiences, I have arrived at the three aspects of quality technical information, which inform all my projects:
It should be discoverable.
It should be readable.
It should be useful.
Principles
Based on Amazon’s Leadership Principles, these principles guide my work in Technical Communications.
Reduce Cognitive Load
Reader Obsession
Many Minds, One Voice
Your Very Smart Friend
Keep it Mnml
Design for Search
You can find out more about these principles in Kai’s Friendly Guide to Technical Writing, and if you’d like to discuss how they can apply to your needs, please reach out to schedule a conversation.
Publications
Recent articles from LinkedIn on topics related to technical writing and editing. You can also check our my LinkedIn posts on these and related topics.
The Customer Information Experience of Technology Products
A framework for designing the information ecosystem of technology products.
Docs as UX
The user experience of a technology product depends on the product documentation.
The Three Aspects of Quality Documentation
For the user, the quality of the documentation reflects the quality of the product.
Principles of Technical Writing
In an era when technical writing has “shifted left” to developer-centric tools and processes, some basic principles to guide the writing of quality documentation.
Five Easy Ways to Improve Your Docs, Part 1: Be the Reader’s Friend
Notes on tone and how to engage the reader with direct address.
Five Easy Ways to Improve Your Docs, Part 2: Break Boulders into Pebbles
The advantages of a topic-basic approach to the information architecture of product documentation.
Five Easy Ways to Improve Your Docs, Part 3: Death to Screenshots!
Make sure your screenshots are providing information, rather than visual and cognitive clutter.
Five Easy Ways to Improve Your Docs, Part 4: Mnmlsm
Guidelines for minimalism in technical writing.
Five Easy Ways to Improve Your Docs, Part 5: Suit the Titles to the Content
Descriptive titles are essential for SEO and content discoverability.
Why You Should Care About Your Docs, as Explained by a Gartner Magic Square
How to improve the perspective on the quality of your product by looking at the quality of your competitor’s documentation.