Blog

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. ...

The blank page remains empty until a writer begins to write. A word processor is a virtual page with a blinking cursor, waiting for the writer to begin. Google is a box with a cursor: Do you feel lucky? ChatGPT is another kind of page, an interface waiting for the writer’s input: Ask it anything. A writer may use a prompt, on paper or on a screen, to begin writing. A sentence emerges from the subconscious, from the interior monologue. We have been taught that a sentence is a complete thought, and the writer builds thought upon thought, sentence upon sentence. ...

Most people optimizing AI chatbots and RAG systems focus on the model. But what if the real problem is your content format? In a head-to-head test, structured content using JSON-LD outperformed standard HTML by more than 3.6x in information retrieval accuracy. The difference is so stark, it’s like comparing finding a book in a heap of books compared to using a card catalog that lists the location of every book. ...

Learn.com published more than 700 structured Frequently Asked Questions articles that contained both a JSON-LD payload and HTML. This post looks at how the FAQ content both supports and does not support interoperable standards for accessible content. Content is accessible via the public endpoint and produces content that can be programmatically queried or ingested and read by a script without any additional work. In addition, the elements in each article are related to a publicly available Schema, the FAQPage schema on Schema.org, which can be used to disambiguate content parts, place them into context, and create a shared representation with anyone using Schema.org. ...

Imagine searching a giant library of documents for one specific answer. It can feel like finding a needle in a haystack. When there’s too much information, getting the useful bits quickly is a big challenge. This is a problem I faced with a large content repository. In response, I built a system that breaks content into chunks and connects those chunks to a taxonomy (an organized set of topics) using important terms found in each chunk. By linking each content piece to key terms and grouping those terms into categories, I created a “map” that makes it easier to find what you need. In this post, I’ll introduce how this works and why it helps with information retrieval (finding the right info when you search). ...

Creating visual diagrams is an essential part of communicating complex systems, relationships, and workflows. However, not all diagrams are created equal. Traditional tools like Microsoft Visio or Adobe Illustrator focus on visual design but often fall short in terms of scalability, automation, and integration. In contrast, semantic diagrams and Diagrams-as-Code offer a transformative approach to diagramming by encoding meaning and enabling automation. This article explores the concept of semantic diagrams, their distinction from traditional tools, the benefits they offer, and how you can leverage them to create powerful, data-driven visualizations. ...

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. ...