Technical Documentation

I had the pleasure of talking to Scott Abel for the podcast Coffee and Content. If you weren’t able to make the talk, you can Register at BrightTalk, and they will send you a link you can use to watch a recording when its convenient for you. From Coffee and Content: Navigate the complexities of using Markdown in large-scale technical documentation projects with insights from Matt Briggs. In this episode of Coffee and Content, Matt will delve into the inherent challenges that arise when Docs-as-Code practices meet expansive tech doc requirements. ...

Ever feel overwhelmed by “walls of text” when trying to learn something new online? That frustration you’re feeling is cognitive overload. Fortunately, there’s a straightforward solution: the concept of the chunk. Chunking is the technique of organizing information into self-contained, coherent units, big enough to make sense, yet small enough to digest comfortably. This simple strategy is the hidden key behind improving readability, enhancing memory retention, and building scalable content systems. ...

Content architecture is a part of information architecture. Saul Wurman, who is credited with creating the term ‘information architecture,’ defines the information architect as ‘The individual who organizes the patterns inherent in data, making the complex clear.’ In content, a content architecture organizes the patterns inherent in content, making the complex clear. Content architecture addresses the problem of disorganized, inconsistent, and hard-to-find information. Even something as small as a single book has a content architecture. Content architecture addresses the solution at scale. Content architecture provides a structured, strategic framework for how content is created, organized, delivered, and maintained to meet both creator, user, and business goals. ...

Over the last three years, I have worked with Christopher Alexander’s A Pattern Language and Robert E. Horn’s Information Mapping. My goal was to create reusable and machine-readable technical documentation for both human readers and generative AI. Alexander warned against modularity because it risks losing the relationships inherent in good design. Despite this, modularity became necessary. Technical documentation requires clarity, consistency, and precision. Modular structures achieve these qualities. To address the tension between Alexander’s organic approach and Horn’s structured methodology, I adopted Horn’s Information Mapping. This method identifies clear information types: procedures, concepts, principles, and facts. Integrating Alexander’s patterns with Horn’s modular approach provided clarity and usability. ...