<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en">
  <title type="text">Andy Fitzgerald Consulting — Articles</title>
  <subtitle type="text">Long-form perspectives, methods and conference notes about information architecture and structured content design for the modern web.</subtitle>
  <link rel="self" type="application/atom+xml" href="https://preview.andyfitzgeraldconsulting.com/insights/feed-articles.xml"/>
  <link rel="alternate" type="text/html" href="https://preview.andyfitzgeraldconsulting.com/insights/"/>
  <id>https://preview.andyfitzgeraldconsulting.com/insights/feed-articles.xml</id>
  <updated>2026-10-08T00:00:00Z</updated>
  <author>
    <name>Andy Fitzgerald</name>
  </author>
  <entry>
    <title type="text">Site Updates: Structure, Semantics &amp; Standards</title>
    <link rel="alternate" type="text/html" href="https://preview.andyfitzgeraldconsulting.com/insights/site-updates-structure-semantics-standards/"/>
    <id>https://preview.andyfitzgeraldconsulting.com/insights/site-updates-structure-semantics-standards/</id>
    <published>2026-10-08T00:00:00Z</published>
    <updated>2026-10-08T00:00:00Z</updated>
    <summary type="text">Four lessons learned from redeveloping my consulting website with LLM code collaboration.</summary>
    <category term="Perspective"/>
    <category term="Content Modeling"/>
    <category term="Structured Content"/>
    <category term="Taxonomy"/>
    <category term="Accessibility Evaluation"/>
    <category term="Performance Evaluation"/>
    <category term="AI Integration"/>
    <content type="html">&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/543a1b6350fe005a669dc5fe4481ec14ae507655-2400x3200.jpg?rect=0,1460,2400,1350&amp;amp;w=1200&amp;amp;h=675&amp;amp;fit=crop&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;675&quot; alt=&quot;Greyscale photography of concrete blocks&quot; /&gt;&lt;/figure&gt;&lt;p&gt;Last week I cut over to a new version of my consulting website. This iteration includes a new short-form &amp;quot;Notes&amp;quot; content type, a richer approach to publishing presentations, and improvements to topical navigation and search. It also includes structural and design updates that make it the most accessible version of the site I&amp;#x27;ve ever built.&lt;/p&gt;&lt;p&gt;It&amp;#x27;s also the first version for which I entrusted the authoring of my site&amp;#x27;s Typescript almost entirely to an LLM. I defined and articulated decisions about the content model, component boundaries, URLs, semantics, and accessibility, and then allowed the LLM to build, test, and iterate the templates and integration scripts that instantiate those choices in code. As Claude Code framed it, &amp;quot;I owned the &lt;em&gt;seams&lt;/em&gt;, and I delegated the &lt;em&gt;surfaces&lt;/em&gt;.&amp;quot;&lt;/p&gt;&lt;p&gt;As you would expect, this division of labor allowed me to get more done in less time. I can write Typescript, but I&amp;#x27;m abysmally slow at it and tend to get mired in Wagnerian struggles with the type-checker. I also don&amp;#x27;t enjoy it. Delegating that work to an LLM was a gift.&lt;/p&gt;&lt;p&gt;The time savings, however, wasn&amp;#x27;t the real benefit. Delegating &amp;quot;surface&amp;quot; work to an LLM significantly changed the quality of the final output I serve to site visitors. The time I might have otherwise spent debugging scripts or puzzling out server configs was now time I could use to explore navigation models, refine search indexing, interconnect content, and expand my coverage of accessibility and linked data affordances.&lt;/p&gt;&lt;p&gt;Looking over this project in retrospect, I can identify four reasons the &amp;quot;seams and surfaces&amp;quot; division led to a higher quality output than I would have otherwise achieved. Here&amp;#x27;s a brief look at each of them.&lt;/p&gt;&lt;h2 id=&quot;structured-content&quot;&gt;Structured Content&lt;/h2&gt;&lt;p&gt;My site has used structured content, built and served with &lt;a href=&quot;https://www.sanity.io/&quot;&gt;Sanity&lt;/a&gt;, since 2022. Since its first iteration, my content model has been structured around the formal characteristics of each content type, as opposed to the page templates on which content appears. This deliberately decouples the way content is structured from the way it is presented on any given page, which in turn shifts the process of adding new types from one of &amp;quot;rebuilding&amp;quot; the model to one of &amp;quot;recomposing&amp;quot; elements already in place.&lt;/p&gt;&lt;p&gt;As an example, on the previous version of my site I listed all of my past talks by venue and date on a single page. To get details on the topic of a talk, a visitor had to click through to the venue link and read the talk description (assuming the conference site was still live, of course). For the redesign I added descriptions, slide decks and, where available, recordings and transcripts to each presentation. I also gave each presentation a detail page of its own.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/b6ebf4eaf06c59bd2c4e02e0dcc00392961c9210-3020x1884.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;749&quot; alt=&quot;Two versions of the Talks/Presentations page, with the earlier version listing only talk locations and dates, while the updated version includes images, descriptions, decks, and more. &quot; /&gt;&lt;figcaption&gt;Talks listed on the 2024 version of the site and the more detail rich display of Presentations on the 2026 redesign. &lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;While I did have to create a new &amp;quot;Presentation&amp;quot; type to record new information, the &amp;quot;Event&amp;quot; type that was driving the previous view needed only minor modifications to accommodate new fields. Instead of being the source of the listing (as on the old page), this type was recomposed as a dependent part of the new Presentation type.&lt;/p&gt;&lt;p&gt;By defining this new &amp;quot;seam&amp;quot; of the revised content model up front, the LLM building the templates for these new pages already had all the typed data that appears on them, structured to reflect the conceptual shift in how I had remodeled that content. Using typescript as a translation layer from schema design to front-end implementation gave the LLM a machine-readable specification for mapping my Figma design into composable templates (the &amp;quot;surface&amp;quot;).&lt;/p&gt;&lt;p&gt;There was still iteration and fine tuning in the template creation process, but a clear and intentionally structured content schema gave the model far less to guess at or get wrong. This meant I could spend my time reconciling the gaps between content schema and UI design and focus on building a more harmonious system overall.&lt;/p&gt;&lt;h2 id=&quot;semantics&quot;&gt;Semantics&lt;/h2&gt;&lt;p&gt;The formal characteristics of a content type are useful for understanding how to structure and articulate a content model. They do nothing, however, to describe what a given piece of content is about, what it means. That&amp;#x27;s the role of semantics. For the last few years I&amp;#x27;ve managed the semantic relationships between content instances with standards-based taxonomies, built and governed in Sanity using the &lt;a href=&quot;https://github.com/andybywire/sanity-plugin-taxonomy-manager&quot;&gt;Taxonomy Manger plugin&lt;/a&gt; (which I wrote and maintain 😉).&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/92e200a276d1ae845939c5fb9df47d7b742a125e-2996x1858.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;744&quot; alt=&quot;A view of a plugin operating in the Sanity platform, displaying a hierarchical list of terms, and detail page of an individual term.&quot; /&gt;&lt;figcaption&gt;The Taxonomy Manager plugin running in Sanity Studio.&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;Managing content semantics and content structure separately allows each of these elements to co-evolve with minimal disruption to the other — and provides a clear seam that helps an LLM not muddle the two.&lt;/p&gt;&lt;p&gt;For example, I&amp;#x27;ve long wanted to include faceted filtering on my &amp;quot;Insights&amp;quot; page. With a seam that clearly distinguished content semantics from content structure, I was able specify the pattern and logic that afford that functionality in Figma, then let the LLM find the best way to code that into a reusable component.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/400924dfbf5104d4f4c0014e98c0525b583d98dd-3020x1884.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;749&quot; alt=&quot;The Insights and Presentations pages from the redesigned site, showing similar facet filter options. &quot; /&gt;&lt;/figure&gt;&lt;p&gt;Since the semantic layer is independent of content types, the pattern worked equally well for the Presentations page, which had also gotten more complex with the redesign.&lt;/p&gt;&lt;p&gt;The separation of content semantics from content structure likewise meant that the seam defined by faceted filtering applied equally well to the Search Results page, which combines all types and genres across both top level nav categories.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/a04b5221d373a6c81d315161b4d248a92116525d-2996x1858.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;744&quot; alt=&quot;The search results page from the redesigned website, showing a similar set of facet filters to the Insights and Presentations pages.&quot; /&gt;&lt;/figure&gt;&lt;p&gt;In each of these cases, the separation of structure from semantics allowed me to more easily integrate the new and revised types into the established system of meaning and create a clear seam to pass the the LLM for collaboration on the surface work.&lt;/p&gt;&lt;h2 id=&quot;standards&quot;&gt;Standards&lt;/h2&gt;&lt;p&gt;The taxonomies described above are structured in alignment with the &lt;a href=&quot;https://en.wikipedia.org/wiki/Simple_Knowledge_Organization_System&quot;&gt;Simple Knowledge Organization System (SKOS)&lt;/a&gt; standard, the W3C recommendation for taxonomies, thesauri, and other kinds of controlled vocabularies. Standards-based vocabularies are interoperable with other semantic web technologies by design, which means that extending them to new types and technologies is accounted for from the start. Since these standards are well-established and open, it also means that LLMs already know how to interpret and build with them.&lt;/p&gt;&lt;p&gt;Established and open standards were likewise an important &amp;quot;seam&amp;quot; in ensring accessibility across the new site. Well-structured, standards-compliant semantic HTML already does most of the heavy lifting of providing accessible content to visitors using assistive technologies. As with SKOS, LLMs already have broad context on implementing standards-compliant HTML and using ARIA attributes to fill in the inevitable gaps that remain.&lt;/p&gt;&lt;p&gt;By specifying a seam for template design that prioritized standard markup, the LLM was able to use the context built into its training corpus to recommend semantic and standards-compliant components, and even pushed back on ideas that could have created accessibility dead zones, keyboard traps, or overly verbose screen reader descriptions.&lt;/p&gt;&lt;p&gt;Compared to the previous site, Lighthouse accessibility scores improved from a range of between 84 and 96 to 100 across all pages, and &lt;a href=&quot;https://wave.webaim.org/&quot;&gt;WAVE&lt;/a&gt; and manual browser testing indicate a broad improvement in structural elements, use of ARIA roles and properties, and clear navigation affordances.&lt;/p&gt;&lt;h2 id=&quot;delegate-and-validate&quot;&gt;Delegate and Validate&lt;/h2&gt;&lt;p&gt;As this point, it&amp;#x27;s fair to ask: &amp;quot;But ... is the generated code any good?&amp;quot; As is common with LLM-driven development, it created more code (nearly 3x more) than I had in the previous version of the site. This iteration does, however, use a different static site generator (Astro versus 11ty, my decision), includes enhanced UI features, live previews, and CI testing for accessibility, link integrity, and performance budgets. Some growth in the codebase isn&amp;#x27;t a huge surprise, but the increase is non-trivial.&lt;/p&gt;&lt;p&gt;The average &lt;em&gt;page&lt;/em&gt; weight the site delivers to site visitors, on the other hand, is less than 20% of the previous load (from 1,817 KB to 222 KB median first load). It is also more accessible than the previous version and uses several hundred megabytes less space on my server (from 630 MB to 94MB).&lt;/p&gt;&lt;p&gt;Could the code be less verbose than it is? Perhaps. More importantly, though, I can account for and explain the purpose of every script and component, and I can map each to a design intent. To me this clarity warrants the extra weight in the repository. It reassures me that I haven&amp;#x27;t (knowingly) included any &amp;quot;black boxes&amp;quot; that may or may not turn out to be bombs later.&lt;/p&gt;&lt;p&gt;There are times I enjoy writing code by hand (not Typescript, of course). I&amp;#x27;ve missed that a bit on this project. But choosing to delegate to the LLM the tasks the LLM is good at has allowed me to spend more time on the tasks that I&amp;#x27;m good at, and that has been surprisingly uplifting. It&amp;#x27;s also helped me build in a way that&amp;#x27;s different than I would have done on my own. Not just faster, but clearer, lighter, and more accessible for the folks who visit my site. It&amp;#x27;s helped me build the kind of website I actually want to use, and of that, I&amp;#x27;m a fan.&lt;/p&gt;</content>
  </entry>
  <entry>
    <title type="text">GraphCon 2026 Themes &amp; Takeaways</title>
    <link rel="alternate" type="text/html" href="https://preview.andyfitzgeraldconsulting.com/insights/graphcon-2026-themes-takeaways/"/>
    <id>https://preview.andyfitzgeraldconsulting.com/insights/graphcon-2026-themes-takeaways/</id>
    <published>2026-08-05T00:00:00Z</published>
    <updated>2026-08-05T00:00:00Z</updated>
    <summary type="text">Summary of the top themes and insights from the 2026 GraphCon conference in Seattle.</summary>
    <category term="Conference Themes"/>
    <category term="Taxonomy"/>
    <category term="Knowledge Graphs"/>
    <category term="Technology Integration"/>
    <content type="html">&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/6395e1c1688e999402714b579635f2de60f5e404-1024x768.jpg?rect=0,192,1024,576&amp;amp;w=1024&amp;amp;h=576&amp;amp;fit=crop&amp;amp;auto=format&quot; width=&quot;1024&quot; height=&quot;576&quot; alt=&quot;A view of a presenter and her title slide from six rows back in an office space turned small conference venue. &quot; /&gt;&lt;/figure&gt;&lt;p&gt;Two weeks ago I had the pleasure of attending the first GraphCon Seattle event. This inaugural practitioners conference, planned and produced by the Graph Geeks community, focused on how folks are solving real world problems in practical ways, using a range of technologies and approaches. Though a one day event, it was packed with thought-provoking perspectives and rich with opportunities to talk with other graph enthusiasts exploring and trying out new ideas with graph approaches to information and knowledge management.&lt;/p&gt;&lt;p&gt;Two weeks ago I had the pleasure of attending the first &lt;a href=&quot;https://www.graphgeeks.org/graphcon&quot;&gt;GraphCon Seattle&lt;/a&gt; event. This inaugural practitioners conference, planned and produced by the &lt;a href=&quot;https://www.graphgeeks.org/&quot;&gt;Graph Geeks&lt;/a&gt; community, focused on how folks are solving real world problems in practical ways, using a range of technologies and approaches. Though a one day event, it was packed with thought-provoking perspectives and rich with opportunities to talk with other graph enthusiasts exploring and trying out new ideas with graph approaches to information and knowledge management.&lt;/p&gt;&lt;p&gt;&lt;/p&gt;&lt;p&gt;Graph Geeks generously plans to make videos of all the talks available on &lt;a href=&quot;https://www.youtube.com/@GraphGeeksOrg&quot;&gt;their YouTube channel&lt;/a&gt;, so keep an eye on that space to check out the talks first-hand. In the meantime, here’s a rundown of the themes and takeaways that emerged for me across the day’s talks and across my conversations with other practitioners.&lt;/p&gt;&lt;h2 id=&quot;top-themes-takeaways&quot;&gt;Top Themes &amp;amp; Takeaways&lt;/h2&gt;&lt;h3 id=&quot;1-value-drives-adoption-no-one-cares-that-youre-using-a-graph&quot;&gt;1. Value drives adoption — no one cares that you’re using a “graph”&lt;/h3&gt;&lt;p&gt;This theme will strike you as ridiculously obvious, because “of course value drives adoption.” We’re all smart, reasonable professionals, making sound decisions based on solid information. Right? Setting aside high irony for a moment, there’s another challenge for graph enthusiasts: we’re &lt;em&gt;really&lt;/em&gt; excited by the technology. This means that even when we know we shouldn’t, it’s hard to resist talking to someone about “the graph.” As Brad Bebee with Amazon Neptune points out, “graph” itself is not an intrinsic benefit. Building support for the solutions graphs provide means finding and clearly articulating the benefits those solutions will provide for the organization — and (ideally) stopping there.&lt;/p&gt;&lt;p&gt;&lt;/p&gt;&lt;p&gt;It’s this last part that is hard for graph practitioners to follow through on. Himanshu Singh recounted that in the process of moving from proof-of-concept to day-to-day graph operations with Netflix, they removed the word “graph” from messaging to stakeholders and collaborators. They even went so far as to remove the word from the name of their project group. Singh advises against “onboarding” your users. You should instead meet them where they are. If people using your solution have to learn a query language or the care and feeding of graph models, you’ve failed. The better outcome is one where they don’t know they’re using graph technology at all. (Mercifully there are events like GraphCon where the graph nerds can properly nerd.)&lt;/p&gt;&lt;h4 id=&quot;talks&quot;&gt;&lt;strong&gt;Talks&lt;/strong&gt;&lt;/h4&gt;&lt;ul&gt;&lt;li&gt;“The Business of Graphs in the Age of AI,” Brad Bebee, AWS Neptune&lt;/li&gt;&lt;li&gt;“The Last Mile of Graphs: Lessons from Production at Netflix,” Himanshu Singh, Netflix&lt;/li&gt;&lt;/ul&gt;&lt;h3 id=&quot;2-graphs-are-evolving-systems&quot;&gt;2. Graphs are evolving systems&lt;/h3&gt;&lt;p&gt;This one was kind of obvious … and kind of not. For those of us coming from the IA and taxonomy world, of course models and implementations have to evolve. An information model is no more “one and done” than is quarterly business planning (hence, you know, its quarterly-ness). But there are some aspects of graph work that can feel settled: top-level ontologies and industry standard taxonomies change slowly and provide stability against fast-changing market pressures. In his talk, “Connected Intelligence: How Graphs Transform AI,” David Hughes makes the argument that in intelligently connected systems, AI should also transform the graph. As Hughes puts it, evolving systems should “return the consequences [of an operation] back to memory.” These “remembered consequences” become part of the graph.&lt;/p&gt;&lt;p&gt;&lt;/p&gt;&lt;p&gt;Yohei Nakajima refers to this as “moving toward an ever-evolving ontology.” In this scenario, ontologies are never “finished,” but are rather a way to represent and understand the state of an agent. The benefit is to mitigate or eliminate the limitations of session-based AI in a scalable and transparent way. Dave Bechberger provides some of my favorite descriptions of this problem: as Bechberger puts it, AI’s “goldfish problem” stems from “session amnesia” and a “re-derivation tax,” where discovered facts must be continually rediscovered. Markdown context documents are a workaround for session-to-session memory, but it’s with graphs that we can approach durable memory for long running processes. Bechberger again: “Vectors remember what. Graphs remember how it relates, and when it was true.”&lt;/p&gt;&lt;h4 id=&quot;talks&quot;&gt;&lt;strong&gt;Talks&lt;/strong&gt;&lt;/h4&gt;&lt;ul&gt;&lt;li&gt;“Connected Intelligence: How Graphs Transform AI,” David Hughes, HDC&lt;/li&gt;&lt;li&gt;“Graphs After RAG: From Knowledge to Context,” Yohei Nakejima, Untapped Capital&lt;/li&gt;&lt;li&gt;“From Goldfish to Elephant: Using Graphs for Long Term Memory,” Dave Bechberger, Stitch Fix&lt;/li&gt;&lt;/ul&gt;&lt;h3 id=&quot;3-its-all-about-the-models&quot;&gt;3. It’s all about the models&lt;/h3&gt;&lt;p&gt;One of my favorite motifs across talks was the idea that the real value graph-minded work delivers is not a set of technologies, but rather the models that graph technologies are used to represent. Brad Bebee makes the point that “you don’t need a graph database to use a graph model.” Indeed, the collection of Markdown documents many folks are using for session-to-session AI context are essentially graph models already. Bebee advises that the opportunity before us as graph practitioners is to “be ready to help [these folks] do this better.”&lt;/p&gt;&lt;p&gt;&lt;/p&gt;&lt;p&gt;As an IA/UX professional who came into the field when mobile browsers were just starting to gain traction, this combination of model centrality and learning systems maps cleanly in my mind to a practice our industry has honed over many years: progressive enhancement. This is the idea that the systems we design, be they responsive websites or agentic workflows, should &lt;em&gt;start&lt;/em&gt; with the basic, core functionality we intend to deliver, they layer on speed, performance, and aesthetic &lt;em&gt;enhancements&lt;/em&gt; as the context of use allows. Crucially, should any of these enhancements fail, the core, basic functionality must remain operational. When combined with AI, a graph is an &lt;em&gt;enhancement &lt;/em&gt;of the underlying model. Building these models right, and ensuring that they evolve consistently over time, is far more important than which database we choose or whether we represent data as triples or nodes, edges, and properties.&lt;/p&gt;&lt;h4 id=&quot;talks&quot;&gt;&lt;strong&gt;Talks&lt;/strong&gt;&lt;/h4&gt;&lt;ul&gt;&lt;li&gt;“The Business of Graphs in the Age of AI,” Brad Bebee, AWS Neptune&lt;/li&gt;&lt;/ul&gt;&lt;h3 id=&quot;4-polyglot-systems&quot;&gt;4. Polyglot systems&lt;/h3&gt;&lt;p&gt;There’s an ongoing (and certainly faux) controversy in some corners of the graph community over which representation of graph data is “better”: Resource Description Frameworks (RDF) or Labeled Property Graphs (LPG). I was delighted to discover that the GraphCon community was having none of this “controversy” nonsense. Himanshu Singh described a project his team ran on a semantic (RDF) graph on the back end, transformed to a property (LPG) graph on the front end, and which was then accessed by end-users that didn’t know they were using a “graph” at all. David Bechberger likewise frames the roles of vector stores and graph stores as fundamentally complementary: each supports the other by filling in where the other is weak — and getting out of the way when it’s poorly suited for a given task.&lt;/p&gt;&lt;p&gt;&lt;/p&gt;&lt;p&gt;As someone who learned a second language as an adult, I have a personal appreciation for the benefits of polyglotism. Having a second language at one’s disposal opens up new worlds of literature, film, and culture — to say nothing of one’s experience as a traveler. Beyond these first order benefits, however, the &lt;em&gt;process&lt;/em&gt; of learning and operating in a new language generates new insight into one’s native language. Once I had to learn to speak and think outside of English, my understanding of what makes it work (and what makes it fail) changed entirely.&lt;/p&gt;&lt;p&gt;&lt;/p&gt;&lt;p&gt;When applied to how we model data, a polyglot approach likewise offers promise for both first and second order benefits. Moving between, for example, RDF and LPG, allows us to choose the right set of capabilities for the task at hand. It also encourages us to scrutinize the underlying model that each is meant to represent and challenge the decisions and structures that result from thinking primarily in one idiom or the other.&lt;/p&gt;&lt;h4 id=&quot;talks&quot;&gt;&lt;strong&gt;Talks&lt;/strong&gt;&lt;/h4&gt;&lt;ul&gt;&lt;li&gt;“The Last Mile of Graphs: Lessons from Production at Netflix,” Himanshu Singh, Netflix&lt;/li&gt;&lt;li&gt;“From Goldfish to Elephant: Using Graphs for Long Term Memory,” Dave Bechberger, Stitch Fix&lt;/li&gt;&lt;/ul&gt;&lt;h3 id=&quot;5-informed-delegation&quot;&gt;5. Informed delegation&lt;/h3&gt;&lt;p&gt;As an event focused on practitioners and real world solutions, GraphCon presentations did not shy away from code examples and live demos. Talks and hallway conversations likewise grappled head-on with the question of how much code one actually writes any more, as opposed to generating with the assistance of LLMs. BoundaryML CEO Vaibhav Gupta stated the case for machine generation directly: “it’s no longer possible to keep up with code subsystems … but we can constrain them.” Indeed, as I understand it, that’s the whole purpose of BAML, the “agent-first” language his company creates.&lt;/p&gt;&lt;p&gt;&lt;/p&gt;&lt;p&gt;Hallway conversations with developers likewise revealed a surprisingly uniform acquiescence to the changing role of individuals in the code creation process. One developer I spoke with said he hardly writes anything by hand any more — and doesn’t miss it. Instead he prefers spending more time with the problem solving and strategy work that informs the scaffolding and constraints he puts in place for the LLM. We’re still in the early days of sorting out what these agent assisted workflows look like — and how to make them consistently reliable — but one thing I didn’t run into were devs pining away for the good old days of writing error handling code and hunting down missing semicolons.&lt;/p&gt;&lt;h4 id=&quot;talks&quot;&gt;&lt;strong&gt;Talks&lt;/strong&gt;&lt;/h4&gt;&lt;ul&gt;&lt;li&gt;“Code is Just a Graph,” Vaibhav Gupta, Boundary (BAML)&lt;/li&gt;&lt;/ul&gt;&lt;h2 id=&quot;the-year-of-the-graph&quot;&gt;The year of the graph?&lt;/h2&gt;&lt;p&gt;There was an ongoing joke throughout the day about how many consecutive years over the last few decades have been proclaimed “The Year of the Graph” … and about how flatly each of those predictions have fallen. This was a laid-back enough crowd that I felt like everyone enjoyed the self-deprecating humor. At the same time, there was a palpable sense that graph approaches and technologies are finally finding a compelling, widespread use case as a complement to generative LLMs in the way that modern software is created and maintained. Is this finally “the year of the graph”? I won’t venture a guess, but if it is there’s a good chance that those doing the work won’t use the word “graph” in describing the value they deliver.&lt;/p&gt;</content>
  </entry>
  <entry>
    <title type="text">Sanity Everything*[NYC] Conference Themes &amp; Takeaways</title>
    <link rel="alternate" type="text/html" href="https://preview.andyfitzgeraldconsulting.com/insights/sanity-everything-nyc-conference-themes-takeaways/"/>
    <id>https://preview.andyfitzgeraldconsulting.com/insights/sanity-everything-nyc-conference-themes-takeaways/</id>
    <published>2025-09-30T00:00:00Z</published>
    <updated>2025-09-30T00:00:00Z</updated>
    <summary type="text">Conference and courtyard themes from Sanity’s first “Everything*[NYC]” developer conference.</summary>
    <category term="Conference Themes"/>
    <category term="Sanity"/>
    <category term="Technology Integration"/>
    <category term="AI Integration"/>
    <content type="html">&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/b4a27c48ff3f1bb4548590b4815cca20abd978af-4032x3024.png?rect=321,722,2925,1645&amp;amp;w=1200&amp;amp;h=675&amp;amp;fit=crop&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;675&quot; alt=&quot;Conference MC Simeon Griggs giving a behind the scenes look at the Sanity Learn platform&quot; /&gt;&lt;/figure&gt;&lt;p&gt;Last week I had the pleasure of attending &lt;a href=&quot;https://sanity.io/&quot;&gt;Sanity&lt;/a&gt;’s first annual “Everything*[NYC]” developer conference. This one-day event was packed with perspectives, feature demos, and customer stories showcasing the leaps forward Sanity has made in the last year—and shining a light down the path of where they’re headed in the rapidly evolving content creation and management space.&lt;/p&gt;&lt;p&gt;Everything*[NYC] was a &lt;em&gt;product &lt;/em&gt;conference, as opposed to a discipline or industry conference. The sessions and demos were thus expectedly rosy. I’m a fan of both the tools Sanity creates and the philosophy that informs them, so this all landed well with me. The consulting work I do, however, focuses first and foremost on my clients’ needs, so I was likewise keen to explore the edges of the programmed narrative with Sanity developers, customers, potential customers, and fellow agency partners in courtyard conversations throughout the day.&lt;/p&gt;&lt;p&gt;In that spirit, read on for my themes and takeaways from the event. I’ll cover what I’m seeing (and am enthused about) from Sanity, what I heard from peers and colleagues in the courtyard, and share a nerdy milestone that I’m counting as a small personal victory in my quest to wean folks away from the idea that “content” necessarily means “pages.”&lt;/p&gt;&lt;h2 id=&quot;platform-themes&quot;&gt;Platform Themes&lt;/h2&gt;&lt;p&gt;The single overarching theme for the day as a whole was “AI” (i.e. LLM) integration into the Sanity platform. Sanity co-founders Magnus Hillestad and Simen Svale et this context with a morning keynote focused on the difference between &lt;em&gt;replacing &lt;/em&gt;work with technology (i.e. most approaches in the recent “AI” deluge) and &lt;em&gt;rewiring &lt;/em&gt;work with technology. They drew a parallel to the (first) industrial revolution, where technology initially displaced individual workers, then, in a fast-follow second act, changed the infrastructure of how work was done altogether, creating new economies of scale and new opportunities.&lt;/p&gt;&lt;h3 id=&quot;agent-actions&quot;&gt;Agent Actions&lt;/h3&gt;&lt;p&gt;Agent Actions provide one example of how Sanity is building infrastructure to not just use AI, but to rewire content work around it. Agent Actions allow developers to code functions that use integrated LLMs to perform defined operations on content using other content as context. This last piece is what piques my interest most: prompts can be managed as documents, and actions can programmatically search and use other content in a collection as context.&lt;/p&gt;&lt;p&gt;As an example, The Met shared an agent action they use to automatically evaluate content against their ten page style guide as part of the publication process. One &lt;em&gt;could &lt;/em&gt;do this with NLP, or one &lt;em&gt;could &lt;/em&gt;try to get authors to apply these rules assiduously, but in my experience, the former approach tends to be fussy and brittle, and the latter approach makes me feel like a schoolmarm with a penchant for hitting children with rulers. (You’re welcome for that mental image.) The agent action means that these checks happen for every document that gets published, and it does so without requiring additional review steps from content producers.&lt;/p&gt;&lt;p&gt;A second case study, presented by &lt;a href=&quot;https://www.linkedin.com/in/laurenherdman/&quot;&gt;Lauren Herdman&lt;/a&gt; of Mejuri, demonstrated how Mejuri uses an agent action to systematically find, reuse, and repurpose content across their collection to increase consistency and cut down on duplication. At first glance this might sound routine, but the struggle of organizations to understand what content they have and avoid recreating content that already exists is real—and costly. As with The Met example above, these are checks that can be applied every time a piece of content is changed. This is work that is theoretically possible with the right discipline and structure … but which I’ve never seen pulled off at scale in the real world.&lt;/p&gt;&lt;h3 id=&quot;reshaping-content-problems-to-fit-the-new-wiring&quot;&gt;Reshaping Content Problems to Fit the New Wiring&lt;/h3&gt;&lt;p&gt;Everything*[NYC] was explicitly billed as a developer conference, so I wasn’t too surprised to see the content design decisions that make the new tech work getting less stage time. Sean Grove (OpenAI &amp;amp; Netlify) did, however, discuss the need to “reshape the problems we address” to take advantage of emerging AI infrastructure by destructuring them to run across multiple agents. Grove’s thesis focused on the development process and creating actionable specifications for AI agents, but this sentiment rings equally true to the way we structure information in the schemas and content models with which those agents operate.&lt;/p&gt;&lt;p&gt;In my experience, many organizations—including those using cutting edge platforms like Sanity—still tend to think of their content as “pages.” The Met style guide example from above, clocking in at “ten pages,” is a case in point. If that guide is like any other I’ve seen, it is composed of an extensive set of directives that work together systematically to create an intended outcome. Loading that ten page document into an LLM context window is certainly a first step in adjusting to this new infrastructure, but it also brings the problem’s old “shape” to our shiny new solution. Sanity has given developers the ability to model information like this as classified, distinct assertions from day one. There’s a bit more planning and set-up involved, but this provides a shape that can be indexed, managed, and composed at scale, both for humans (yes, often as pages) and as data for the bots increasingly among us.&lt;/p&gt;&lt;p&gt;This brings me to a corollary to the “rail” example of the industrial revolution. Railway right-of-ways &lt;em&gt;literally &lt;/em&gt;paved the way for the uninhibited place-to-place connections needed for telegraph, which had repercussions not possibly imagined by those laying the first rail lines. Will integration with AI provide the right-of-way for destructuring our content into systematically related propositions, as opposed to the blobby page construct that’s been with us since moveable type nudged us into mass literacy? We’ll see!&lt;/p&gt;&lt;h2 id=&quot;courtyard-themes&quot;&gt;Courtyard Themes&lt;/h2&gt;&lt;p&gt;Across the several conversations I had with current and prospective Sanity customers and fellow agency colleagues, two themes emerged with conspicuous regularity: folks are still struggling with the chaos of connecting content across product silos, and folks are still locked deep in a mindset of “content as pages.”&lt;/p&gt;&lt;p&gt;As with the writing guide example discussed above, the tools for breaking out of the “pages” mindset are already at hand. Bridging silos is a pricklier task (see &lt;a href=&quot;https://www.linkedin.com/in/davemccomb/&quot;&gt;Dave McComb&lt;/a&gt;’s &lt;em&gt;Software Wasteland &lt;/em&gt;and&lt;em&gt;The Data-Centric Revolution &lt;/em&gt;for all the gory details), but shares a similar root cause with the “pages” problem: idiosyncratic information models across across silos (and pages) make connecting the facts, concepts, and ideas they share in common a manual task.&lt;/p&gt;&lt;p&gt;A large enough language model could maybe make some of those connections with almost reasonable accuracy, but those same models can also help us structure content in a way that simpler models (or simply taxonomies) could make those connections with far greater accuracy.&lt;/p&gt;&lt;p&gt;As above: We’ll see! I’m encouraged, however, that, even if some organizations’ inertia keeps them from following an “ideal” path toward structured content, we at least have the tools for taking incremental steps toward creating the structural and semantic foundations that can keep our newly wired AI workplaces from going completely, well, “off the rails.” (Sooo many metaphors 🙄)&lt;/p&gt;&lt;h2 id=&quot;one-small-nerd-victory&quot;&gt;One Small Nerd Victory&lt;/h2&gt;&lt;p&gt;This is only a “theme” inasmuch as it occurred more than once, but occasionally, when I introduced myself to someone new, they would respond with, “Oh, you’re the taxonomy guy.” Guilty as charged! 🎉&lt;/p&gt;</content>
  </entry>
  <entry>
    <title type="text">Content Modeling in the Age of Flying Cars</title>
    <link rel="alternate" type="text/html" href="https://preview.andyfitzgeraldconsulting.com/insights/content-modeling-in-the-age-of-flying-cars/"/>
    <id>https://preview.andyfitzgeraldconsulting.com/insights/content-modeling-in-the-age-of-flying-cars/</id>
    <published>2025-08-26T00:00:00Z</published>
    <updated>2025-08-26T00:00:00Z</updated>
    <summary type="text">Structuring and connecting content for the next generation of AI-integrated CMS.</summary>
    <category term="Perspective"/>
    <category term="Content Modeling"/>
    <category term="Structured Content"/>
    <category term="Interoperability"/>
    <category term="AI Integration"/>
    <content type="html">&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/3f0c188e3734580c4a00c0ac66e7e3b8bae246a2-4096x2304.jpg?rect=468,183,3159,1777&amp;amp;w=1200&amp;amp;h=675&amp;amp;fit=crop&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;675&quot; alt=&quot;Three paper airplanes suspended by threads against a cerulean blue background.&quot; /&gt;&lt;/figure&gt;&lt;p&gt;Next-generation content management platforms use generative AI to help content teams work beneath and beyond the traditional “page” — but only if you can reliably tell them how your content is connected in meaningful, repeatable ways. Fortunately, you already have the tools to build the model your new platform needs.&lt;/p&gt;&lt;p&gt;In these heady and sometimes head-spinning few years since GPT3 appeared, those of us responsible for planning, producing, and maintaining content have had a lot to figure out. How do we ensure our content is seen, understood, and trusted now that the internet is being flooded with AI generated output? How do we get trustworthy information to audiences who prefer to use AI mediated tools like Perplexity or “AI Overviews”? How do we effectively and responsibly use LLMs in strategy and production to create higher quality content more efficiently?&lt;/p&gt;&lt;p&gt;In response to these and many other questions, content management system (CMS) vendors have been busy expanding their features and functionality. We now have access to built-in AI assisted idea generators and ghostwriter assistants. We have integrated machine learning based translation and personalization support for audience segments. Several tools also now have support for integrated MCP servers that connect directly to AI assistants and platform native vector stores that enable semantic search.&lt;/p&gt;&lt;p&gt;For the few vendors that are truly integrating these tools throughout their stack, these aren’t just incremental improvements: they’re pushing leading platforms into an entirely new category. Where traditional CMSes cater to the two dimensional flat plane of the page—what’s on the page, in what order, and what comes before and after—emerging platforms move authors beyond the familiar trappings of headings and layouts to represent facts, concepts, and ideas as richly connected entities in a defined domain of knowledge.&lt;/p&gt;&lt;p&gt;If one were to imagine the traditional, page-based CMS as the serviceable Ford Fiesta that got us reliably from print to online content, the emerging CMS of 2025 is the flying car of content management. These are systems free from the earthbound constraints of the flat page—with all the opportunity and all risk that that entails.&lt;/p&gt;&lt;h2 id=&quot;beyond-and-beneath-the-page&quot;&gt;Beyond and Beneath the Page&lt;/h2&gt;&lt;p&gt;The flying car CMS is not just a collection of bolted-on features. Platforms truly engineered for AI integration allow producers and strategists to work confidently in two new directions on an entirely new axis: beyond the page and beneath the page.&lt;/p&gt;&lt;p&gt;Features like personalized audience segments, automated translation, entity linking, and flexible serialization (for example to JSON-LD, llms.txt, or agents.md) are examples of working &lt;em&gt;beyond&lt;/em&gt; the page. In many cases it still makes sense to produce pages as well, but working beyond that page means you can represent your content as richly interconnected data files, markdown, or speakable text, all with the same first class support that is traditionally given to pages.&lt;/p&gt;&lt;p&gt;The flying car CMS also enables you to reach &lt;em&gt;beneath&lt;/em&gt; the page, capturing and providing granular access to the facts, concepts, and ideas that come together to form a how-to article, a product description, or an orchestrated multimedia experience. These deeply integrated AI tools give content producers production, tagging, and research superpowers—and free them from the tedious copying and pasting between fields that plagues so many existing systems.&lt;/p&gt;&lt;h2 id=&quot;still-stuck-in-traffic&quot;&gt;Still Stuck in Traffic&lt;/h2&gt;&lt;p&gt;For all the truly stunning advances we’re seeing with modern content platforms, there is one trap I see organizations fall into again and again when implementing a next generation CMS. They’ve bought the new software, they’ve integrated it with their front end, they’ve onboarded their team … but their content model includes the same constraints—and often the same structure—as their previous platform. They’ve loaded everyone into their shiny new flying car, but they’re still navigating with a paper map of roads and highways, stuck in the same gridlock they swore they were leaving behind.&lt;/p&gt;&lt;p&gt;How does this happen? The content model “map” is only part of the problem. Even if you’ve evaluated your content model and created a new, revised content schema in your new platform, if you’ve used the same &lt;em&gt;cartographic elements&lt;/em&gt; you used before—the same trappings and habits of page-based design—you remain limited to the two dimensions the page affords.&lt;/p&gt;&lt;p&gt;If this distinction between schemas and models, or maps and cartography, sounds fussy and pedantic, let me offer two more comparisons to help you relate: Only a truly reckless pilot would take off not knowing the approach vectors, safe altitudes, and navigation aids necessary to safely land. Only a foolhardy skipper would set sail without knowing the depths, underwater hazards, or prevailing currents along their route. A roadmap has affordances for neither of these navigation contexts; aeronautical and marine charts do and afford safe passage for those who use them wisely.&lt;/p&gt;&lt;p&gt;A better map, which is to say a more expressive and robust schema, begins with a more robust and expressive conceptual model. These models are achieved by stepping back from the page and identifying the facts, concepts, and ideas your pages are meant to communicate, and then modeling those elements to support the coordinated ensemble of people, process, and technology (including AI) you use to create content. This process is called Domain Driven Content Modeling.&lt;/p&gt;&lt;h2 id=&quot;domain-driven-content-modeling&quot;&gt;Domain Driven Content Modeling&lt;/h2&gt;&lt;p&gt;Every organization operates within a specific sphere of influence and activity. This is &lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/insights/domain-modeling/&quot;&gt;your organization’s “domain&lt;/a&gt;.” By aligning on and articulating the goals you’re working to achieve within your domain, you can more easily identify the relevant attributes and relationships common to your content. These are the facts, concepts, and ideas germane to the actual work you do, the “differences that make a difference” for your organization.&lt;/p&gt;&lt;p&gt;Every organization also produces content with a specific combination of people, process, and technology. This is your approach to “content operations.” Your content operations may include a team of 20 people using established workflows across a highly polished tech stack, or it may be one person periodically updating markdown files on a geriatric Thinkpad. If your organization creates content, you already have an approach to content operations: it&amp;#x27;s either working toward your goals, or it&amp;#x27;s working against them.&lt;/p&gt;&lt;p&gt;Your content model sits at the center of your content operations. It describes your organization’s content structure (types, objects, and attributes) and content semantics (the formal relationships between structural elements, taxonomy terms, and business rules). In a domain driven approach to content modeling, the design of the content model is explicitly informed by the goals your organization is working to achieve within your domain, and the opportunities and constraints inherent to your people, process, and technology. It’s an approach to content modeling that isn’t based on the formal characteristics of the pages you publish, but rather on the &lt;em&gt;work you actually do.&lt;/em&gt;&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/e4b021011e1db06d0c880f22258f4cea006ed98a-2600x1600.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;738&quot; alt=&quot;A Venn diagram with People, Process, and Technology labels and their overlapping parts combined with the label &amp;quot;Content Modeling,&amp;quot; surrounded by a circle labeled &amp;quot;Content Ops,&amp;quot; which is inside a circle labeled &amp;quot;Business Goals,&amp;quot; which is inside a circle labeled &amp;quot;Domain.&amp;quot;&quot; /&gt;&lt;/figure&gt;&lt;p&gt;If you create documentation for medical equipment, for example, a domain driven content model might capture set-up, operation, and troubleshooting steps for a particular machine. These are not stored as blocks of free text under generic headings, but as structured objects in a machine readable sequence associated with defined use cases and equipment models. Likewise, if you produce footwear from a range of different materials, your content model may capture provenance and cleaning information for each type of material. Descriptions for products using these materials can then draw from a central store of facts to describe where the materials were sourced and how to care for them.&lt;/p&gt;&lt;p&gt;Your content producers may still be &lt;em&gt;composing&lt;/em&gt; in a page-based UI—it’s what authors know and are comfortable with—but when the underlying model is not limited by page constraints, CMS integrated AI assistants can draw on the underlying structure and relationships &lt;em&gt;beneath&lt;/em&gt; the page to make informed suggestions, reduce time searching for information, and allow producers to focus on the activities where they produce the most value. Once produced, this content can appear both as a page and &lt;em&gt;beyond&lt;/em&gt; that page as machine readable markup or plain text optimized for generative AI.&lt;/p&gt;&lt;h2 id=&quot;how-to-get-started&quot;&gt;How to Get Started&lt;/h2&gt;&lt;p&gt;As you can by now surmise, the first step in creating a domain driven content model has nothing to do with code. The CMS is often where the domain model is realized as a concrete entity—even in a “flying car” CMS—but this doesn’t mean its creation is an engineering task alone. In addition to meeting technical requirements, the content model should support the needs and capabilities of content producers and coordinate the requirements of your strategy, production, authorization, and publication process. Your organization’s goals within its domain drive the selection of what gets represented and at what level of granularity, and how those elements relate to other parts of the model.&lt;/p&gt;&lt;p&gt;Fortunately, most of the techniques for gathering this information are well established and widely available. Stakeholder alignment, process modeling, contextual inquiry, and content auditing can all provide valuable insight into the cartographic elements needed to structure a well connected, domain driven content model. Methodologies like the &lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/insights/structured-content-design-22/&quot;&gt;Structured Content Design Workflow&lt;/a&gt; can help you plan and stage these activities and work toward a domain-based model that allows you to work on, beneath, and beyond the page.&lt;/p&gt;&lt;p&gt;You also don’t need to tackle the whole model at once. The leading vendors in the “flying car” CMS space have built in affordances and workflows for change management over time. Use these to introduce a domain-driven approach in stages—and to support continued evolution once you’ve effectively moved beyond the two dimensional constraints of the page.&lt;/p&gt;&lt;p&gt;Whichever approach you take, consider not only the model you’re using to orchestrate your content operations at present, but also the concepts and “cartographic language” you make available to your model-building process. When it comes to managing content, the long-awaited age of flying cars is (metaphorically) finally here. We’re all still learning how to navigate these new horizons, but one thing that’s certain is that this new territory will need a new kind of map—and a fresh perspective on how we plan, build, and share the content we create.&lt;/p&gt;&lt;p&gt;&lt;br/&gt;&lt;/p&gt;</content>
  </entry>
  <entry>
    <title type="text">Content Operations Strategy and Design</title>
    <link rel="alternate" type="text/html" href="https://preview.andyfitzgeraldconsulting.com/insights/content-operations-strategy-design/"/>
    <id>https://preview.andyfitzgeraldconsulting.com/insights/content-operations-strategy-design/</id>
    <published>2025-07-07T00:00:00Z</published>
    <updated>2025-07-07T00:00:00Z</updated>
    <summary type="text">Designing and building systems for planning, creating, publishing, and managing content.</summary>
    <category term="Perspective"/>
    <category term="Content Modeling"/>
    <category term="Governance"/>
    <content type="html">&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/132a0c0d6760d6634fbfb028723442fa63055ce4-2400x1600.jpg?rect=0,250,2400,1350&amp;amp;w=1200&amp;amp;h=675&amp;amp;fit=crop&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;675&quot; alt=&quot;Road curving through a forest of tall trees in a dark forest with a beam of light shining down&quot; /&gt;&lt;/figure&gt;&lt;p&gt;In the last several years, we’ve witnessed seismic shifts in how content is created, communicated, and consumed. To communicate effectively online, we now need models that transcend the page and treat content as a living asset, ready to flow wherever it creates value. While Information architecture remains essential, the holistic operationalization of how content is planned, created, published, and managed is now more crucial than ever. This is why I’m narrowing the scope of my practice to “content operations engineering and design,” with a focus on work with the Sanity platform.&lt;/p&gt;&lt;p&gt;For the last fifteen years I’ve framed my work primarily as “information architecture”: I help make complex information spaces easy to understand and pleasant to use. This work has always been about communication—helping teams convey facts, concepts, and ideas so audiences understand what matters. Often, the focus has been on creating pages (despite my &lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/presentations/conversations-with-robots-voice-ai-structured-content/&quot;&gt;perennial efforts&lt;/a&gt; to move beyond that metaphor).&lt;/p&gt;&lt;p&gt;In the last several years, we’ve witnessed seismic shifts in how content is created, communicated, and consumed. That we’ve moved past “pages” is a foregone conclusion. To communicate effectively online we now need models that treat content as a living asset, ready to flow wherever it creates value. Information architecture remains essential. The holistic operationalization of how content is planned, created, published, and managed, however, is now more crucial than ever. This is why I’m narrowing how I define the scope of my practice to “content operations strategy and design,” with a focus on modern content operations platforms.&lt;/p&gt;&lt;p&gt;I realize this is a bit of a mouthful, so let me unpack it piece by piece.&lt;/p&gt;&lt;h2 id=&quot;content-operations&quot;&gt;Content Operations&lt;/h2&gt;&lt;p&gt;&lt;em&gt;Content operations&lt;/em&gt; is the coordinated ensemble of &lt;strong&gt;people, process, and technology&lt;/strong&gt; an organization uses to plan, create, govern, and measure the effectiveness of content. Purposeful, outcomes-focused content operations guide both human authors and generative algorithms in the creation of trustworthy, effective content.&lt;/p&gt;&lt;p&gt;In my practice, I’ve found that creating a successful approach to content operations relies on three interdependent activities:&lt;/p&gt;&lt;ol&gt;&lt;li&gt;&lt;strong&gt;Discovery and alignment:&lt;/strong&gt; uncovering an organization’s communication goals, domain language, and author realities&lt;/li&gt;&lt;li&gt;&lt;strong&gt;Thinking in systems&lt;/strong&gt;: designing models, services, and workflows that scale beyond individual documents and consider communication goals across contexts&lt;/li&gt;&lt;li&gt;&lt;strong&gt;Engineering for intended outcomes:&lt;/strong&gt; building structure and guidance into the content operations environment so that the creation of on-brand, on-purpose content is the path of least resistance for both humans and machines&lt;/li&gt;&lt;/ol&gt;&lt;p&gt;If you follow my work at all, you know that this is the kind of work I’ve already been doing for years. By formalizing this focus, my goal is to more directly connect with organizations that need help uncovering what must be said, modeling it so it can move fluidly across channels, and embedding those models into workflows that create consistent value.&lt;/p&gt;&lt;h2 id=&quot;strategy&quot;&gt;Strategy &lt;/h2&gt;&lt;p&gt;As &lt;a href=&quot;https://en.wikipedia.org/wiki/Attention_economy#History&quot;&gt;Herbert Simon&lt;/a&gt; observed more than fifty years ago, in an information-rich world, “a wealth of information creates a poverty of attention.” While it has never been easier to create &lt;em&gt;more&lt;/em&gt; content, identifying effective approaches for creating and articulating the &lt;em&gt;right&lt;/em&gt; content reliably and efficiently across channels and contexts remains a challenge. If anything, the proliferation of low quality AI generated content now makes that task even more difficult. &lt;/p&gt;&lt;p&gt;This is where strategy comes in. Creating, publishing, and managing content that furthers organizational goals doesn’t happen on its own. Stakeholders, SMEs, designers, and engineers must be aligned on what those goals are and what constitutes a “win” in achieving them. Teams that are all pulling in different directions can spend a lot of time and energy staying in same spot.&lt;/p&gt;&lt;p&gt;Successful content operations projects build consensus on what they will achieve prior to deciding how they will achieve it. I work with my clients to vet and apply time-tested frameworks for ensuring their strategic approach to content is grounded in measurable business needs, not the latest trends of UI design and front-end development. &lt;/p&gt;&lt;h2 id=&quot;design-engineering&quot;&gt;Design &amp;amp; Engineering&lt;/h2&gt;&lt;p&gt;&lt;a href=&quot;https://articles.centercentre.com/design_rendering_intent/&quot;&gt;Jared Spool&lt;/a&gt; writes that &amp;quot;design is the rendering of intent.” I like to extend this truism by adding that engineering is the realization of design. To move from strategic intent to operational reality, both design and engineering must be carefully coordinated. When misalignment exists between these elements for content operations, organizations can end up with “technically correct” implementations that ignore business requirements and author needs, or visionary design recommendations that never survive handoff.&lt;/p&gt;&lt;p&gt;For &lt;a href=&quot;https://uxdesign.cc/prototyping-information-architecture-11aaccacf9a1&quot;&gt;nearly a decade&lt;/a&gt; I’ve been developing and iterating methods for bridging engineering and design. As part of my focus on content operations, I’ve brought together a set of time-tested frameworks and methods for uncovering and instantiating the requirements for an organization’s content operating systems. These tools allow me to lead projects in which:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;Alignment workshops provide informed input for domain and content models.&lt;/li&gt;&lt;li&gt;Domain and content models directly inform the schemas and components of a working content platform.&lt;/li&gt;&lt;li&gt;Content platforms are embedded alongside training and governance guidance that helps teams take full ownership of their content operating system and its evolution.&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;The systems that emerge are ones that authors actually want to use because they speak their language, support their tasks, and provide effective tools for embracing new ways of creating and managing content.&lt;/p&gt;&lt;h2 id=&quot;modern-content-operations-platforms&quot;&gt;Modern Content Operations Platforms&lt;/h2&gt;&lt;p&gt;For the past five years most of my client work has been deep inside the Sanity ecosystem: I’ve launched studios, written plugins, developed apps, and designed and iterated custom workflows and integrations. I’ve also had a front-row seat as Sanity and other platforms have evolved from capable headless CMSes into full-featured “content operating systems.” For organizations with specialized entities or domain‑specific complexity, the customizable schemas and API‑first workflows of modern tools make them uniquely suited for creating purpose-built content operations solutions.&lt;/p&gt;&lt;p&gt;The openness and flexibility that makes these systems powerful, however, can backfire: Development teams new to composable content are just as free to create implementations that work &lt;em&gt;against&lt;/em&gt; core value propositions as they are to build in a way that embraces them. By committing to understanding the platform and its features deeply, my goal is to help organizations using Sanity and similar tools work &lt;em&gt;with the grain&lt;/em&gt; of these platforms to achieve the operational outcomes that best serve their needs and deliver lasting value over time.&lt;/p&gt;&lt;h2 id=&quot;carrying-on&quot;&gt;Carrying On&lt;/h2&gt;&lt;p&gt;Twenty years ago I pivoted from a career path as an English professor to the then budding field of “UX.” My goal then, as now, has been to understand and enable the creation and sharing of meaning between individuals. The changes wrought by generative AI in the last few years have tossed a lot of what we thought we knew about those practices into an epistemological juice mixer. The outcomes I seek to support, however, remain the same: the communication of ideas from one mind to another.&lt;/p&gt;&lt;p&gt;I’m excited to carry on with this work in this new, weird world of ours. If any of what I’ve written piques your curiosity—or if you find yourself in the thick of any of the challenges I describe above—please do &lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/contact/&quot;&gt;reach out&lt;/a&gt;. I’d love to start a conversation.&lt;/p&gt;</content>
  </entry>
  <entry>
    <title type="text">AI Supported Auto-Categorization</title>
    <link rel="alternate" type="text/html" href="https://preview.andyfitzgeraldconsulting.com/insights/ai-supported-auto-categorization/"/>
    <id>https://preview.andyfitzgeraldconsulting.com/insights/ai-supported-auto-categorization/</id>
    <published>2025-03-03T00:00:00Z</published>
    <updated>2025-03-03T00:00:00Z</updated>
    <summary type="text">A comparison of manual, NLP, and LLM-based tagging methods and key takeaways for effective tagging approaches.</summary>
    <category term="Method"/>
    <category term="Development"/>
    <category term="Automation"/>
    <category term="AI Integration"/>
    <content type="html">&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/f4f8c74f76f015b1cd5afa5fc32d84843c09bdb4-5184x3456.jpg?rect=410,233,4506,2535&amp;amp;w=1200&amp;amp;h=675&amp;amp;fit=crop&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;675&quot; alt=&quot;Four paper tags of different colors with strings attached on a plain white background&quot; /&gt;&lt;/figure&gt;&lt;p&gt;Generative AI offers some enticing shortcuts for tagging large content sets. But even outputs that &amp;quot;look&amp;quot; right might not meet user goals—and may not be any more effective than what can be generated with time-tested natural language processing approaches. This article describes an experiment that compares these two methods to discover the essential ingredients for an effective tagging strategy.&lt;/p&gt;&lt;p&gt;For the last few weeks, I&amp;#x27;ve been exploring ways that AI and LLMs do—and don&amp;#x27;t—fit into taxonomy design and development for content-driven websites. I&amp;#x27;ve written about:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;&lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/insights/ai-taxonomy-term-generation/&quot;&gt;AI Supported Taxonomy Term Generation&lt;/a&gt;, for which I&amp;#x27;ve found there are some compelling use cases for integrating LLMs&lt;/li&gt;&lt;li&gt;&lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/insights/purpose-driven-taxonomy-design/&quot;&gt;Purpose-Driven Taxonomy Design&lt;/a&gt;, in which the primary challenge I see clients struggle with is defining what the taxonomy needs to accomplish (for which you&amp;#x27;ll need to—gasp!—actually talk to other humans)&lt;/li&gt;&lt;li&gt;&lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/insights/sanity-studio-taxonomy-migration/&quot;&gt;Migrating a Taxonomy to the CMS&lt;/a&gt;, which can be significantly streamlined when your work is based on established semantic web standards&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;Once your taxonomy is integrated into your CMS, the next step, naturally, is to tag your content. This is what allows you to put the domain knowledge represented by your taxonomy to use to recommend content, display collections, navigate, support search, inform analytics, surface content opportunities, etc.&lt;/p&gt;&lt;p&gt;If you already have a collection of several thousand accurately tagged articles and you need to tag more, using an enterprise taxonomy tool to train a machine learning model to tag new content may be a feasible way to get this done. If you&amp;#x27;re not in the fortunate position of having a critical mass of accurately tagged content, your options have traditionally been manually slogging through the content set with human taggers, or using deterministic natural language processing (NLP) algorithms and models to assign tags.&lt;/p&gt;&lt;p&gt;But we live in 2025! Surely LLMs can help with this. Right? If you&amp;#x27;ve been on The Internet lately, you&amp;#x27;ve certainly seen examples aplenty of LLMs creating reasonable-looking sets of tags for content, seemingly out of thin air. But are these tags effective? And are they any better than what a human tagger or NLP process would produce?&lt;/p&gt;&lt;h2 id=&quot;an-experiment&quot;&gt;An Experiment&lt;/h2&gt;&lt;p&gt;Since the content set I&amp;#x27;ve been using as a running example in the last few articles is small enough for one person to tag manually, I took the opportunity to conduct an experiment. I ran human, NLP, and LLM tagging approaches on a sample set of articles to evaluate each approach for consistency.&lt;/p&gt;&lt;p&gt;My hypothesis, based similar experiences I&amp;#x27;ve had with recent client work, was that the (deterministic) NLP approach would be at least as accurate as the LLM approach, and would, in the final implementation, involve less overhead that keeping an LLM from going off the rails.&lt;/p&gt;&lt;p&gt;It turns out that I was wrong.&lt;/p&gt;&lt;p&gt;But I was not wrong in the way I expected to be: A comparison of methods showed not the inherent differences of one algorithmic approach over the other—or even over manual human tagging. Rather, each approach produced a result that &lt;em&gt;looked&lt;/em&gt; right ... but that may or may not be effective for achieving the user-centered goals intended.&lt;/p&gt;&lt;p&gt;In short, I was reminded that you can&amp;#x27;t do human-centered design without input from the humans for whom the design is intended. 🤷‍♂️&lt;/p&gt;&lt;p&gt;In the spirit of sharing this rediscovery of the obvious—and with the suspicion that it might be a useful reminder for others in these heady AI times—here&amp;#x27;s a look at:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;the small sample size experiment I ran with human, deterministic, and LLM-based auto-tagging&lt;/li&gt;&lt;li&gt;the outcomes and the findings produced &lt;/li&gt;&lt;li&gt;a perspective on managing and setting expectations for tagging projects in our nascent era of ubiquitous LLMs&lt;/li&gt;&lt;/ul&gt;&lt;h2 id=&quot;auto-tagging-approaches&quot;&gt;Auto-Tagging Approaches&lt;/h2&gt;&lt;p&gt;To establish a baseline for what an appropriate set of tags should include, I first manually tagged all the articles in the content collection in question with four terms each from the new taxonomy. This took roughly four hours (not counting breaks—of which I needed plenty).&lt;/p&gt;&lt;p&gt;I also enlisted two experienced information architecture colleagues to tag the three most difficult and the three easiest articles. They were given the same parameters I used to tag content myself: aim for four tags per article focused on the article&amp;#x27;s overall topic, its &amp;quot;aboutness,&amp;quot; in light of the intended audience and use cases for the content and the site. (My colleagues were much faster than I was—it turns out I&amp;#x27;m a lousy scanner).&lt;/p&gt;&lt;h3 id=&quot;natural-language-processing-auto-tagging&quot;&gt;Natural Language Processing Auto-Tagging&lt;/h3&gt;&lt;p&gt;Natural Language Processing (NLP) uses linguistic models and rules-based interpretation methods to deterministically generate information about natural language texts. The NLP process I set up to tag the six sample articles used &lt;a href=&quot;https://www.sbert.net/&quot;&gt;BERT sentence transformers&lt;/a&gt; to calculate semantic similarity between a given article and the definition of each taxonomy term at three levels:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;&lt;strong&gt;Document similarity&lt;/strong&gt; compared the entire article to each taxonomy term definition&lt;/li&gt;&lt;li&gt;&lt;strong&gt;Paragraph similarity&lt;/strong&gt; compared each paragraph to taxonomy term definitions and selected the highest-scoring terms&lt;/li&gt;&lt;li&gt;&lt;strong&gt;Sentence similarity&lt;/strong&gt; compared each sentence to taxonomy term definitions and selected the highest-scoring terms&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;I then weighted these scores for each term, with the document score carrying the most weight (60%) and the maximum sentence score carrying the least (10%). This produced a final similarity score for each term definition, of which the top four were selected as tags. This process took 2.5 hours to set up and run.&lt;/p&gt;&lt;p&gt;👉 &lt;a href=&quot;https://github.com/andybywire/auto-cat/blob/main/nlp-tagging.ipynb&quot;&gt;View the annotated NLP Auto-Tagging Jupyter Notebook&lt;/a&gt;&lt;/p&gt;&lt;h3 id=&quot;large-language-model-auto-tagging&quot;&gt;Large Language Model Auto-Tagging&lt;/h3&gt;&lt;p&gt;Finally, I used OpenAI&amp;#x27;s GPT-4o-mini to tag articles via LLM. Since 4o&amp;#x27;s context window can handle 128,000 tokens, I was able to feed it an entire article &lt;em&gt;and&lt;/em&gt; the entire taxonomy, including definitions, for each article to be tagged. I set the temperature of the model to zero to limit fanciful embellishment and loquacious asides.&lt;/p&gt;&lt;p&gt;As you would expect, it took some experimentation and iteration to get the prompt right, but I was eventually able to get the model to return a set of appropriate tag labels as a JSON file I could compare with the other results. This process took about two hours overall and incurred a total of $0.93 cents in API fees.&lt;/p&gt;&lt;p&gt;👉 &lt;a href=&quot;https://github.com/andybywire/auto-cat/blob/main/llm_tagging.ipynb&quot;&gt;View the annotated LLM Auto-Tagging Jupyter Notebook&lt;/a&gt;&lt;/p&gt;&lt;h2 id=&quot;results&quot;&gt;Results&lt;/h2&gt;&lt;p&gt;To assess the consistency of each approach, I calculated the Jaccard index across all possible combinations of tag results. For two sets of values, which in this case amounts to up to eight tags, the Jaccard index calculates the similarity and diversity between the sets by dividing the intersection of the sets (the count of which values they have in common) by the union of the sets (the total number of unique values between them).&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/d5ab989196ac1a33803f05d684767f31725aee64-4800x1828.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;457&quot; alt=&quot;Two Venn diagrams, one showing the intersection sets, the other showing the union of sets. Between them is a division symbol, indicating that the intersection is divided by the union.&quot; /&gt;&lt;figcaption&gt;A Jaccard index divides the intersection of sets by the union of sets&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;The results, shown in the heat map below, indicate the average degree of agreement between individual tagging agents: three humans, one NLP process, and one LLM process. One is complete agreement. Zero means that the set of tags provide by each were completely different.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/d21986eebea7b5506ce81182fb82ed892889ef0e-1920x1440.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;900&quot; alt=&quot;A Tagger Agreement heatmap, showing that all taggers, both human and algorithmic, agreed no more than 35% and no less than 17%.&quot; /&gt;&lt;/figure&gt;&lt;p&gt;None of these are what I would consider strong results for &lt;em&gt;any&lt;/em&gt; pair—including pairs of human taggers. Likewise, neither the NLP nor the LLM process represent a significant difference in the consistency offered by manual tagging.&lt;/p&gt;&lt;p&gt;So how do we know which set of tags is the most effective for the goals established for this content collection (and outlined in the &lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/insights/purpose-driven-taxonomy-design/&quot;&gt;Purpose Driven Taxonomy Design&lt;/a&gt; article)? We would need to know which approach is able, from the user&amp;#x27;s point of view, to:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;coordinate content recommendations&lt;/li&gt;&lt;li&gt;communicate the range of topics covered&lt;/li&gt;&lt;li&gt;afford topic-based browsing&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;Even if the three human taggers had stronger agreement on which tags to choose for each article, this &lt;em&gt;still&lt;/em&gt; doesn&amp;#x27;t tell us that those tags will achieve these goals for users in the context in which they&amp;#x27;ll encounter them. To discover this answer, we need to engage not with some new tool or learning model, but rather with the actual users themselves.&lt;/p&gt;&lt;p&gt;As a fairly seasoned UX professional, this finding wasn&amp;#x27;t exactly a shocker. What did take me by surprise was how &lt;em&gt;equally worthless&lt;/em&gt; each of the three techniques I tried above is in the absence of this user insight. With so much attention focused on what LLMs can do, it&amp;#x27;s somehow refreshing to be starkly reminded that human-centered design still requires human involvement in a fundamental way.&lt;/p&gt;&lt;h2 id=&quot;takeaways&quot;&gt;Takeaways&lt;/h2&gt;&lt;p&gt;Fortunately, there are several common and well-established methods for collecting this missing insight.&lt;/p&gt;&lt;h3 id=&quot;prior-to-tagging&quot;&gt;Prior to Tagging&lt;/h3&gt;&lt;p&gt;If it&amp;#x27;s important that your taxonomy and tagging strategy meet improvement goals at launch, you&amp;#x27;ll want to engage with users before you start tagging content, and ideally before you finalize your taxonomy. Two common and well-established methods for accomplishing this are:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;Tree testing, which uses a raw, text-based &amp;quot;tree&amp;quot; of topic tags to test out candidate structures with potential users&lt;/li&gt;&lt;li&gt;Prototype usability testing, which presents potential users with a mocked-up version of a content collection (and its hierarchy) and leads them to complete a set of defined tasks with the proposed design&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;Both of these are effective, low-cost ways to vet a proposed topic hierarchy and tagging approach prior to implementation. They can also be effective ways to find out if your labels and categories deliver the &amp;quot;information scent&amp;quot; needed to guide users to related topics and content.&lt;/p&gt;&lt;p&gt;These techniques only work, of course, if you actually do them. Asking a bot or a &amp;quot;synthetic user&amp;quot; (🙄) to complete a task has become infinitely easier in recent months, but unless those bots &lt;em&gt;are your users&lt;/em&gt;, you&amp;#x27;re only adding a new, equally ambiguous column to the &amp;quot;Tagger Agreement&amp;quot; heat map above.&lt;/p&gt;&lt;h3 id=&quot;after-tagging&quot;&gt;After Tagging&lt;/h3&gt;&lt;p&gt;For some projects, getting the taxonomy and tagging strategy right at launch is not mission-critical. The content collection I&amp;#x27;m using as an example in these articles falls into this category. In this case, I&amp;#x27;ll use data from the traffic and click path analytics and user feedback to help me collect the insight I&amp;#x27;ll need to iterate and improve the taxonomy and tagging strategy over time.&lt;/p&gt;&lt;p&gt;Indeed, even if you have front-loaded user research with tree testing and usability testing, monitoring a taxonomy&amp;#x27;s performance and adapting it to new uses and contexts is an ongoing pursuit. This process is called governance, and it is indispensable to maintaining a taxonomy&amp;#x27;s effectiveness over time.&lt;/p&gt;&lt;p&gt;As with &amp;quot;before tagging&amp;quot; approaches, evidence-based iteration and purposeful governance only work if you actually &lt;em&gt;do&lt;/em&gt; them. The care and feeding of a taxonomy is a requirement that catches many organizations new to vocabulary control by surprise. It remains, however, vitally important to ensuring the lasting value of taxonomy and tagging efforts.&lt;/p&gt;&lt;h2 id=&quot;setting-expectations&quot;&gt;Setting Expectations&lt;/h2&gt;&lt;p&gt;It would seem, then, that in the absence of front-loaded user research, using an LLM to tag content offers no appreciable advantage over deterministic NLP approaches to auto-categorization. Without user input, neither approach is much more than an exercise in theoretical tag generation.&lt;/p&gt;&lt;p&gt;Since taxonomies are ultimately systems intended to support human behavior in all of its variance and unpredictability, it is hard to imagine an algorithmic approach replacing human creators and maintainers outright. While there certainly appear to be opportunities for automated processes to take some of the tedium and repetition out of this work, it is only by purposefully incorporating the fundamentals of user-centered design that we will achieve results that both &amp;quot;look right&amp;quot; and deliver the outcomes intended for the people who must use them.&lt;/p&gt;</content>
  </entry>
  <entry>
    <title type="text">Sanity Studio Taxonomy Migration</title>
    <link rel="alternate" type="text/html" href="https://preview.andyfitzgeraldconsulting.com/insights/sanity-studio-taxonomy-migration/"/>
    <id>https://preview.andyfitzgeraldconsulting.com/insights/sanity-studio-taxonomy-migration/</id>
    <published>2025-02-11T00:00:00Z</published>
    <updated>2025-02-11T00:00:00Z</updated>
    <summary type="text">Instructions, templates, and scripts for migrating a taxonomy from a spreadsheet into the Taxonomy Manager tool on Sanity CMS.</summary>
    <category term="Method"/>
    <category term="Technology Integration"/>
    <category term="Taxonomy"/>
    <content type="html">&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/66de94e98e4755bbf2139eaf75d385646148801f-3018x1538.png?rect=136,0,2734,1538&amp;amp;w=1200&amp;amp;h=675&amp;amp;fit=crop&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;675&quot; alt=&quot;A single taxonomy structure shown on two screens, the first in a spreadsheet, and the second in a custom taxonomy management tool in Sanity Studio.. &quot; /&gt;&lt;/figure&gt;&lt;p&gt;Developing a taxonomy to meet the business needs of your content collection is a crucial step toward regaining control of your content ecosystem. Too often, however, well-intentioned taxonomy solutions never fully make it to the systems they&amp;#x27;re meant to serve. Don&amp;#x27;t let this be your fate! Here&amp;#x27;s the process I use to migrate taxonomy drafts in a spreadsheet to the taxonomy management tool in Sanity CMS.&lt;/p&gt;&lt;p&gt;In recent articles, I&amp;#x27;ve discussed &lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/insights/ai-taxonomy-term-generation/&quot;&gt;using AI to generate taxonomy terms&lt;/a&gt; and &lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/insights/purpose-driven-taxonomy-design/&quot;&gt;using a purpose-driven design process for shaping those terms into a taxonomy that meets business and user needs&lt;/a&gt;. None of this does any good, however, if your shiny new taxonomy sits moldering in a spreadsheet and never makes it to your production environment. (You would be alarmed by how often this happens. Alarmed.)&lt;/p&gt;&lt;p&gt;In this article I&amp;#x27;ll share the process I use to migrate a taxonomy from a spreadsheet to the taxonomy management tool in &lt;a href=&quot;https://www.sanity.io/&quot;&gt;Sanity CMS&lt;/a&gt;. I realize, of course, that not everyone&amp;#x27;s into Sanity. So it goes. While this example will focus on a Sanity implementation, the principles and core elements of the migration approach are not platform dependent. If you need a starting point for migrating taxonomy terms on a different platform, read on—I&amp;#x27;ll give guidance along the way on how you can adapt this process to other contexts.&lt;/p&gt;&lt;h2 id=&quot;embracing-standards&quot;&gt;Embracing Standards&lt;/h2&gt;&lt;p&gt;Whatever tech stack you use, embracing open, shared standards is a cornerstone of creating interoperable, reusable content ecosystems. The interoperability that comes with the use of standards is particularly important to the implementation of a taxonomy for (at least) two reasons.&lt;/p&gt;&lt;p&gt;First, taxonomies are living documents. To remain effective, they must change and evolve—sometimes growing, sometimes shrinking or consolidating to more effectively meet business needs. Embracing a standards-based approach helps you support this inherent change by making updates and evolution predictable and by allowing you to support your taxonomy with different tooling as your feature set, team, and business require.&lt;/p&gt;&lt;p&gt;Second, taxonomies often serve as the &amp;quot;connective tissue&amp;quot; between knowledge systems. Taxonomy is literally the shared vocabulary that allows different systems to &lt;em&gt;mean&lt;/em&gt; the same thing when they &lt;em&gt;say&lt;/em&gt; a particular thing. When your own taxonomy is based on predictable, shared standards, you&amp;#x27;ll be more likely to communicate directly with other standards-based applications, services, and vocabularies.&lt;/p&gt;&lt;h2 id=&quot;the-migration-script&quot;&gt;The Migration Script&lt;/h2&gt;&lt;p&gt;The &lt;a href=&quot;https://www.sanity.io/schemas/import-taxonomy-terms-b46af03f&quot;&gt;script&lt;/a&gt; we&amp;#x27;ll use to migrate terms from spreadsheet to CMS-based management tool relies on adherence to the W3C&amp;#x27;s &lt;a href=&quot;https://www.w3.org/TR/skos-reference/&quot;&gt;Simple Knowledge Organization System (SKOS)&lt;/a&gt; standard in both the &lt;a href=&quot;https://docs.google.com/spreadsheets/d/1eWaO_8pOdC7QwN4umnRnniEVFECMUc1b42FA3Ea7D0c/edit?gid=1890562484#gid=1890562484&quot;&gt;source spreadsheet&lt;/a&gt; and the &lt;a href=&quot;https://www.sanity.io/plugins/taxonomy-manager&quot;&gt;destination tool&lt;/a&gt;. This is just one example of how following standards can make moving between environments smooth and painless (or at least less painful). If I eventually need to move this taxonomy &lt;em&gt;out&lt;/em&gt; of Sanity in order to take advantage of the features of a standalone taxonomy management tool, working with a standards-based structure will make that move much less painful in turn.&lt;/p&gt;&lt;p&gt;At a high level, this script:&lt;/p&gt;&lt;ol&gt;&lt;li&gt;defines a concept scheme based on script settings&lt;/li&gt;&lt;li&gt;creates concepts by extracting preferred labels from the taxonomy hierarchy, mapping metadata to SKOS keys used by the &lt;a href=&quot;https://www.sanity.io/plugins/taxonomy-manager&quot;&gt;Taxonomy Manager Plugin&lt;/a&gt;, and adding `broader` concept relationships based on hierarchy&lt;/li&gt;&lt;li&gt;adds concepts to concept scheme array&lt;/li&gt;&lt;li&gt;creates a single transaction to import into the designated Sanity content store&lt;/li&gt;&lt;/ol&gt;&lt;p&gt;The core logical problem that makes this script more than just &amp;quot;content migration&amp;quot; happens in step two. This is where we map the hierarchy from the end-user-friendly spatial layout of the spreadsheet to a set of relationships that represent the formal, standards-based relationships the Taxonomy Manager plugin expects (and enforces).&lt;/p&gt;&lt;pre&gt;&lt;code class=&quot;language-javascript&quot;&gt;// 3c. Map concepts to the hierarchy
  if (conceptLevel == 0) {
    // Top Concept
    hierarchy = [currentConceptRef] // reset hierarchy with new top concept
    previous = currentConceptRef // set previous to the current concept _ref for the next iteration
    topConceptSet = true
  } else if (conceptLevel == 1 &amp;amp;&amp;amp; topConceptSet == false) {
    // L1 concept with no top concept
    hierarchy = [currentConceptRef] // reset hierarchy with new concept
    previous = currentConceptRef
  } else if (
    conceptLevel - 1 == previous.level || // Child concept
    conceptLevel == previous.level || // Sibling concept
    conceptLevel &amp;lt; previous.level // Ancestor concept
  ) {
    mapChildConcept(
      hierarchy,
      currentConcept,
      broaderDetected,
      conceptLevel,
      currentConceptRef,
      toRemove,
    )
  } else if (conceptLevel &amp;gt; previous.level + 1) {
    // Orphan concept: two or levels lower than previous term
    throw new Error(&apos;Inconsistent Hierarchy: Orphan term.&apos;)
  }&lt;/code&gt;&lt;/pre&gt;&lt;p&gt;As this code block in the mapping function moves through each term in the supplied &lt;code&gt;.csv&lt;/code&gt;, it tracks which terms immediately precede it and assigns a level of hierarchy based on the relative position of each term. This allows us to detect child, sibling, and ancestor concepts, as well as new instances of Top Concepts or first-level concepts where no Top Concept is present. These relationships are then added as references to the &lt;code&gt;broader&lt;/code&gt; array of the term in question.&lt;/p&gt;&lt;p&gt;If you&amp;#x27;re importing your taxonomy into a different platform, the details of how you connect and upload to that system will change, but the basic structure of extracting the hierarchy and mapping it to a SKOS concept scheme should be adaptable—if not something you can just drop into your implementation (provided you&amp;#x27;re using standards-compliant tools, of course). Check out the &lt;a href=&quot;https://www.sanity.io/schemas/import-taxonomy-terms-b46af03f&quot;&gt;full script on Sanity Exchange&lt;/a&gt; for annotations and explanations of the additional functions and processes that support this core structure.&lt;/p&gt;&lt;h2 id=&quot;the-workflow&quot;&gt;The Workflow&lt;/h2&gt;&lt;p&gt;I explored &lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/insights/purpose-driven-taxonomy-design/&quot;&gt;purpose-driven taxonomy design&lt;/a&gt; in a recent article. That post provides a high level process for deciding what terms to include in your taxonomy and how to structure them. Once you&amp;#x27;ve defined, tested, and vetted your taxonomy, you can use these steps to migrate it into your instance of Sanity CMS.&lt;/p&gt;&lt;h3 id=&quot;preparing-the-taxonomy&quot;&gt;Preparing the Taxonomy&lt;/h3&gt;&lt;p&gt;The migration script is designed to work with a &lt;code&gt;.csv&lt;/code&gt; file exported from &lt;a href=&quot;https://docs.google.com/spreadsheets/d/1eWaO_8pOdC7QwN4umnRnniEVFECMUc1b42FA3Ea7D0c/edit?gid=1890562484#gid=1890562484&quot;&gt;this Google Sheets template&lt;/a&gt;. Download the &amp;quot;Taxonomy Template&amp;quot; tab (or whatever you choose to rename it) as a &lt;code&gt;.csv&lt;/code&gt; and add its location as the &lt;code&gt;sourceFile&lt;/code&gt;.&lt;/p&gt;&lt;p&gt;&lt;strong&gt;Taxonomy Preparation Tips&lt;/strong&gt;&lt;/p&gt;&lt;ul&gt;&lt;li&gt;Use only one term per row. This is modeled in the spreadsheet sample data. The script will throw an error if there is more than one term per row or if there is no term specified for a row that otherwise contains metadata&lt;/li&gt;&lt;li&gt;Don&amp;#x27;t repeat terms. All your concept labels must be unique.&lt;/li&gt;&lt;li&gt;Use Top Concepts or L1 only, but not both. L1s will be nested under the nearest top concept if top concepts are used. Read more about &lt;a href=&quot;https://sanitytaxonomymanager.com/#/?id=adding-concepts&quot;&gt;Top Concepts in the Sanity Taxonomy Manager docs&lt;/a&gt;.&lt;/li&gt;&lt;li&gt;Include definitions! Definitions are helpful for your authors and indexers, as well as to any other &amp;quot;agents&amp;quot; (a-hem: 🤖) that may use your terms. Provide examples and scope notes, too, where appropriate. Read more about &lt;a href=&quot;https://www.w3.org/TR/2009/NOTE-skos-primer-20090818/#secdocumentation&quot;&gt;scope notes and examples in the W3C&amp;#x27;s SKOS Primer&lt;/a&gt;.&lt;/li&gt;&lt;/ul&gt;&lt;h3 id=&quot;script-settings&quot;&gt;Script Settings&lt;/h3&gt;&lt;p&gt;Once you have the &lt;code&gt;.csv&lt;/code&gt; saved and the path updated, add a title for the taxonomy scheme and an optional (but recommended) description.&lt;/p&gt;&lt;pre&gt;&lt;code class=&quot;language-javascript&quot;&gt;// 🚨 Change these to your values

const sourceFile = &apos;topic-taxonomy.csv&apos; // required; expects format provided by template linked in description
const conceptSchemeName = &apos;Topic Taxonomy&apos; // required
const conceptSchemeDescription = &apos;A taxonomy of topics used in Sanity Studio&apos; // optional
const baseIri = &apos;https://studio.sanity.io/taxonomy/&apos; // required; your studio domain is usually a good choice&lt;/code&gt;&lt;/pre&gt;&lt;p&gt;You&amp;#x27;ll also add a &lt;code&gt;baseIri&lt;/code&gt;. This is the default URI (Uniform Resource Identifier) for your concepts and concept schemes. Unique identifiers allow for the clear and unambiguous identification of concepts across namespaces, for example between &lt;code&gt;https://shipparts.com/vocab/Bow&lt;/code&gt; and &lt;code&gt;https://wrappingsupplies.com/vocab/Bow&lt;/code&gt;. The base URI of these concepts is &lt;code&gt;https://shipparts.com/vocab/&lt;/code&gt; and &lt;code&gt;https://wrappingsupplies.com/vocab/&lt;/code&gt;, respectively.&lt;/p&gt;&lt;ul&gt;&lt;li&gt;In most cases, it makes sense for your base URI to be a directory or subdirectory of your website.&lt;/li&gt;&lt;li&gt;In all cases, the URI you choose should be in a domain that you control.&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;The &lt;code&gt;baseIri&lt;/code&gt; can be changed later if you need to adjust namespaces after import.&lt;/p&gt;&lt;h3 id=&quot;running-the-script&quot;&gt;Running the Script&lt;/h3&gt;&lt;p&gt;To connect the script with your Sanity Content Lake instance, you&amp;#x27;ll need to include an &lt;code&gt;.env&lt;/code&gt; file with:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;your Sanity project ID&lt;/li&gt;&lt;li&gt;the name of your dataset&lt;/li&gt;&lt;li&gt;an API token with write access&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;With that in place and dependencies installed, run &lt;code&gt;node taxo-tool.js&lt;/code&gt; to migrate your taxonomy. Add flags to test or remove the entire scheme (and all its concepts):&lt;/p&gt;&lt;ul&gt;&lt;li&gt;&lt;code&gt;--test&lt;/code&gt; prints the schema name, the first three concepts, and the total concept count to the terminal. No data is sent to Sanity.&lt;br/&gt;&lt;/li&gt;&lt;li&gt;&lt;code&gt;--remove&lt;/code&gt; removes the taxonomy as configured in the script from your Studio. Use this if you need to make major changes and would rather start fresh.&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;The script is idempotent, so if you update your schema and run it again, it will only change concepts that have been modified. Note that concept and scheme IDs are based on a hash of the concept preferred label (or the scheme title), so if you change labels or the scheme title, you will end up with duplicate entries. In this case you may just want to delete the entire scheme and migrate a fresh version.&lt;/p&gt;&lt;h2 id=&quot;next-steps&quot;&gt;Next Steps&lt;/h2&gt;&lt;p&gt;My hope is that this post helps those of you using Sanity—or another standards-compliant CMS—avoid the embarrassing fate of being stuck with taxonomy shelfware.&lt;/p&gt;&lt;p&gt;The next step, of course, is to start tagging content. In a future post, I&amp;#x27;ll explore some ways you can (responsibly) use LLMs to help with that. I&amp;#x27;ll also discuss how your structure and term definitions (you &lt;em&gt;are&lt;/em&gt; defining your terms, right? right??? 🧐) can help you create consistent, reliable results using purposefully coordinated, resource-appropriate models.&lt;/p&gt;</content>
  </entry>
  <entry>
    <title type="text">Purpose-Driven Taxonomy Design</title>
    <link rel="alternate" type="text/html" href="https://preview.andyfitzgeraldconsulting.com/insights/purpose-driven-taxonomy-design/"/>
    <id>https://preview.andyfitzgeraldconsulting.com/insights/purpose-driven-taxonomy-design/</id>
    <published>2025-01-30T00:00:00Z</published>
    <updated>2025-01-30T00:00:00Z</updated>
    <summary type="text">A purpose-driven process for selecting terms, creating structure, and vetting design approaches on small and large scale taxonomy projects.</summary>
    <category term="Method"/>
    <category term="Taxonomy"/>
    <category term="Usability Testing"/>
    <content type="html">&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/a6f9a65f1c739e90c526548398e13816d6f612b3-4566x1742.png?rect=1469,0,3097,1742&amp;amp;w=1200&amp;amp;h=675&amp;amp;fit=crop&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;675&quot; alt=&quot;A grid of digital sticky notes enumerating UX research and design themes&quot; /&gt;&lt;/figure&gt;&lt;p&gt;A purpose-driven taxonomy is designed to meet a clearly defined set of goals and use cases. This sounds obvious, but it&amp;#x27;s a step many organizations gloss over—often with frustratingly mixed outcomes as a result. In this article, I&amp;#x27;ll discuss a process I use for selecting terms, creating structure, and vetting design approaches on both small and large scale taxonomy projects. I&amp;#x27;ll also offer advice on where LLMs do—and don&amp;#x27;t—fit into a purpose-driven taxonomy design workflow.&lt;/p&gt;&lt;p&gt;In my last post, &lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/insights/ai-taxonomy-term-generation/&quot;&gt;AI Supported Taxonomy Term Generation&lt;/a&gt;, I used an LLM to help generate candidate terms for the revision of a topic taxonomy that had fallen out of sync with the content it was meant to tag. In that example, the taxonomy in question is for the &amp;quot;Insights&amp;quot; articles on &lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/&quot;&gt;my consulting website&lt;/a&gt;. Having generated a set of term updates, the next step is now to decide which terms to include and then create an appropriate structure in which to organize them.&lt;/p&gt;&lt;p&gt;You might be thinking, &amp;quot;Great, throw it back into the LLM!&amp;quot; As many folks (&lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/insights/taxonomy-boot-camp-2024-themes-takeaways/&quot;&gt;among them professional taxonomists&lt;/a&gt;) are figuring out, however, with this approach the devil is in the details. An LLM &lt;em&gt;may&lt;/em&gt; produce a syntactically correct taxonomy that &lt;em&gt;may&lt;/em&gt; conform to reality for a general topic, but you&amp;#x27;ll have to vet and validate each term to know if that&amp;#x27;s what it has done. Not only does correcting dodgy output not save you much time, but it also deprives you of the insight you gain by working through goals, options, and implementation mockups yourself.&lt;/p&gt;&lt;p&gt;This article is an overview of what that process looks like. I&amp;#x27;ll use my Topic Taxonomy revision as a running concrete example and will discuss along the way how these steps scale to larger projects with higher stakes—and more stakeholders. After an introduction to what I mean by &amp;quot;Purpose-Driven Taxonomy Design,&amp;quot; I&amp;#x27;ll discuss:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;Defining taxonomy goals and use cases&lt;/li&gt;&lt;li&gt;Identifying candidate taxonomy terms&lt;/li&gt;&lt;li&gt;Defining relationships (creating the taxonomy&amp;#x27;s structure)&lt;/li&gt;&lt;li&gt;Moving the work into a spreadsheet to revise and refine&lt;/li&gt;&lt;li&gt;Vetting the proposed structure and terms&lt;/li&gt;&lt;li&gt;Migrating the taxonomy to a CMS&lt;/li&gt;&lt;/ul&gt;&lt;h2 id=&quot;purpose-driven-design&quot;&gt;Purpose-Driven Design&lt;/h2&gt;&lt;p&gt;One common misstep I often see project teams make when beginning a taxonomy initiative is to build a taxonomy &amp;quot;of&amp;quot; a topic rather than &amp;quot;for&amp;quot; a purpose. A taxonomy &amp;quot;of&amp;quot; medical conditions, for instance, instead of a taxonomy &amp;quot;for&amp;quot; locating signs, symptoms, and when to see a physician. Or a taxonomy &amp;quot;of&amp;quot; courses offered, instead of &amp;quot;for&amp;quot; locating programs that align with a student&amp;#x27;s interests.&lt;/p&gt;&lt;p&gt;You can avoid this trap by first clearly identifying the goals and use cases your taxonomy needs to support, and then ensuring that the structure proposed meets those goals within the technology constraints at hand. This is a process I often follow when creating taxonomies for clients to support mission-critical operations.&lt;/p&gt;&lt;p&gt;While the tools, inputs, and scale needed to develop an enterprise taxonomy will differ from developing the small, low-stakes taxonomy I discuss here, the basic steps can be applied in both instances—and in both cases will usually result in a taxonomy that is more effective and easier to use, maintain, and iterate as your knowledge management needs evolve over time.&lt;/p&gt;&lt;h2 id=&quot;goals-use-cases&quot;&gt;Goals &amp;amp; Use Cases&lt;/h2&gt;&lt;p&gt;To design a taxonomy &lt;em&gt;for&lt;/em&gt; some intended outcome, you need to know what that outcome is. Yes, I know: this feels too obnoxiously obvious to put down in writing. But here we are. I&amp;#x27;ve seen enough cases of organizations skipping this step and ending up frustrated—or worse, feeling that taxonomy &amp;quot;doesn&amp;#x27;t work&amp;quot;—that I&amp;#x27;ll risk the annoyance.&lt;/p&gt;&lt;p&gt;In the case of my consulting website topic taxonomy, the &lt;em&gt;goals&lt;/em&gt; of the taxonomy are to:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;coordinate content recommendations&lt;/li&gt;&lt;li&gt;communicate the range of topics I write about&lt;/li&gt;&lt;li&gt;afford topic-based browsing&lt;/li&gt;&lt;li&gt;complement site traffic data to show which topics and categories generate the most interest among site visitors&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;These are the outcomes I want the taxonomy to help me achieve. It&amp;#x27;s useful to articulate these, and, if there are multiple stakeholders, align on them. Different goals will suggest different structures and terms. I &lt;em&gt;don&amp;#x27;t&lt;/em&gt; need this taxonomy to support faceted browsing, for instance. It&amp;#x27;s also not a priority (right now) for it to include alternate and non-preferred terms to support search indexing and retrieval.&lt;/p&gt;&lt;p&gt;The &lt;em&gt;use cases&lt;/em&gt; of this taxonomy describe how it will be employed to achieve these goals. For this example, my topic taxonomy needs to:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;support the assignment of multiple tags to accurately represent article topics&lt;/li&gt;&lt;li&gt;support the association of articles that share an identical tag&lt;/li&gt;&lt;li&gt;support the association of articles that share &lt;em&gt;sibling&lt;/em&gt; tags&lt;/li&gt;&lt;li&gt;support the association of articles that share &lt;em&gt;cousin&lt;/em&gt; tags&lt;/li&gt;&lt;li&gt;support end-user browsing by assigned tags&lt;/li&gt;&lt;li&gt;support end-user browsing by all tags&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;For these use cases, associations will be ranked based on how close the relationship between terms is. This means that the specificity of terms should be consistent at different levels of the eventual hierarchy so that terms at similar levels return a predictable number and specificity of results.&lt;/p&gt;&lt;h2 id=&quot;candidate-terms&quot;&gt;Candidate Terms&lt;/h2&gt;&lt;p&gt;With a clear sense of why this taxonomy exists and what it needs to accomplish, I can now make informed decisions about which terms to include. In my &lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/insights/ai-taxonomy-term-generation/&quot;&gt;last article&lt;/a&gt; I showed how to use an LLM to generate a ranked list of candidate terms for a collection of content. I&amp;#x27;ll narrow this list down by choosing terms that are most likely to help me meet the goals defined above for the intended audience of the content and the purpose of the site as a whole.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/b54d0411e7af115190eedd5eaa5de35a27598f26-3023x1725.webp?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;685&quot; alt=&quot;A spreadsheet with a list of recommended tags in the left column, conditionally highlighted statistics in the next three columns, and synthesized definitions for each&quot; /&gt;&lt;figcaption&gt;LLM-generated candidate topic tags.&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;Each term returned from the term generation process includes data for:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;the number of resources to which it was applied&lt;/li&gt;&lt;li&gt;the average relevance score of the tag to its content&lt;/li&gt;&lt;li&gt;the standard deviation of the relevance score&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;This data allows me to first rank terms by those with the highest average relevance and easily identify those with the lowest standard deviation of relevance scores. This means that for most of the content tagged, the relevance was similarly high.&lt;/p&gt;&lt;p&gt;&amp;quot;Information Architecture,&amp;quot; &amp;quot;Content Strategy,&amp;quot; and &amp;quot;Semantic Web,&amp;quot; for example, all have high relevance scores and low standard deviation. The first two of those terms, however, can be applied to most (if not all) articles in the collection. This doesn&amp;#x27;t do much to help with the goal of affording topic-based browsing. A category of &amp;quot;all content&amp;quot; doesn&amp;#x27;t narrow the set down. But they could be good candidate terms for first or second level categories.&lt;/p&gt;&lt;p&gt;Tags with high relevance and a high standard deviation need investigation. By looking at the Raw Tags data returned from the LLM, I can investigate why the range of relevancy scores is broad. For &amp;quot;taxonomy,&amp;quot; for instance, two articles have a low score because taxonomy is part of what they discuss, but isn&amp;#x27;t the main topic of the article. This supports the content recommendation and topic-based browsing goals discussed above.&lt;/p&gt;&lt;p&gt;Some tags, however, like &amp;quot;digital marketing,&amp;quot; have a low standard deviation (0.035) and a reasonable measure of relevance (0.75) but are only used twice. These are relatively weak connections between a small set of resources. They also don&amp;#x27;t align strongly with the site&amp;#x27;s purpose. I&amp;#x27;ll likely leave terms like these out of the first draft.&lt;/p&gt;&lt;h2 id=&quot;relationships&quot;&gt;Relationships&lt;/h2&gt;&lt;p&gt;Once I have a set of candidate terms, it&amp;#x27;s time to sort out how they relate to one another. Like the previous step, this one is driven by the goals and use cases defined for the taxonomy, the needs of the site audience, and the purpose of the content collection.&lt;/p&gt;&lt;p&gt;For larger projects with multiple stakeholders and audiences, card sorting with your content set&amp;#x27;s target audience is a great way to gather evidence for key relationships and structures to consider. Few techniques are as simple to set up and rich in the insights they deliver about users&amp;#x27; mental models.&lt;/p&gt;&lt;p&gt;For this small, low-stakes example, sketching structural approaches in a white-boarding tool like Miro is a good way to explore possible options. I started this process by deduplicating concepts and color-coding them into simple categories based on the candidate term selection step. This helped me keep track of where terms originated and how &amp;quot;important&amp;quot; they are to the overall content set.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/117ead8c69bd479490095f01c5903dbe094a96d2-5120x2880.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;675&quot; alt=&quot;A Miro board showing a grid of sticky notes in three different colors, each with a different taxonomy term written on them&quot; /&gt;&lt;figcaption&gt;Deduplicated candidate terms&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;I then grouped together similar terms, assigning parent terms to groups of similar concepts and explored ways to fit the whole structure together into a single hierarchy. &lt;/p&gt;&lt;p&gt;The approach that initially seemed the most obvious to me was to organize by discipline (Information Architecture, Content Strategy, User Experience Design, etc.), but trying this out quickly showed a problem: many of the tags I had selected belonged in several of these categories at once.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/a34b5de59426ff31eef4f3b9e076dec0abdee272-3366x2242.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;799&quot; alt=&quot;A collection of sticky notes organized in an incomplete hierarchical structure in an online white-boarding tool. &quot; /&gt;&lt;figcaption&gt;Candidate terms organized by discipline&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;While this arrangement is possible—it&amp;#x27;s an approach called &amp;quot;polyhierarchy&amp;quot;—it creates a complex set of relationships to manage. Without a compelling reason for the complexity, it&amp;#x27;s best avoided—particularly as a starting point.&lt;/p&gt;&lt;p&gt;The next approach I tried was to organize terms by &amp;quot;project phase focus.&amp;quot; This strategy allowed me to eliminate the polyhierarchy and resulted in a more balanced set of second and third level categories from the start.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/513fe5482522a5ed62acfe1eaf38338cf6ea39eb-4576x2184.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;573&quot; alt=&quot;A collection of sticky notes organized in a hierarchical structure in an online white-boarding tool. &quot; /&gt;&lt;figcaption&gt;Candidate terms organized by project phase focus&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;This approach also highlighted &lt;em&gt;gaps&lt;/em&gt; in my candidate term set. As I sorted and categorized, I filled in missing concepts from my knowledge of the domain, my content set, my business goals, and my users. These were tags that either provided organizational affordances or weren&amp;#x27;t currently represented in my content set—but which I could reasonably anticipate would be useful for future articles and case studies.&lt;/p&gt;&lt;p&gt;Though this second structure felt like a good starting point, I explored one more approach to stretch my thinking. This third option uses a &amp;quot;discipline focus by phase&amp;quot; strategy that swaps the first and second level categories.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/a3d3bde4d12b4d44bf88b5d5384cff39f12dce6e-4646x2334.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;603&quot; alt=&quot;A collection of sticky notes organized in a hierarchical structure in an online white-boarding tool. &quot; /&gt;&lt;figcaption&gt;Candidate terms organized by discipline focus phase&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;This version isn&amp;#x27;t the worst thing in the world, but it creates duplication at level two that would require longer (more specified) labels for those terms. It is also less balanced than the &amp;quot;project phase by focus&amp;quot; approach. This would mean that tags in some branches could artificially create more connections than others, just by virtue of their structure.&lt;/p&gt;&lt;p&gt;As neither of these features works to support my goals and use cases, &amp;quot;project phase by focus&amp;quot; is the model I&amp;#x27;ll move forward with. If you&amp;#x27;re collaborating with other designers, engineers, or business stakeholders, vetting your selection at this step in a visual tool can be a great way to gather feedback. Virtual whiteboards and sticky notes can be easier for some audiences to handle than spreadsheets—which is where we&amp;#x27;re heading next.&lt;/p&gt;&lt;h2 id=&quot;define-revise-and-refine&quot;&gt;Define, Revise, and Refine&lt;/h2&gt;&lt;p&gt;While digital white-boarding tools like Miro can be a great place to draft structural approaches, the most common tool for revising and vetting a taxonomy is the ubiquitous spreadsheet. Spreadsheets allow you to easily share and iterate your draft, and, if properly formatted, give you a structure you can import into a standards-compliant taxonomy management tool.&lt;/p&gt;&lt;p&gt;A note on &amp;quot;proper formatting&amp;quot;: make sure each record (in this case, each taxonomy term) is in its own row. This is a convention I often see skipped, and it makes migrating your structure to a production tool much more complicated than it needs to be. For a primer on data structures for designers, see Tim Sheiner&amp;#x27;s excellent article &amp;quot;&lt;a href=&quot;https://medium.com/salesforce-ux/designers-field-guide-to-data-a573693cdea8&quot;&gt;Understanding Data&lt;/a&gt;.&amp;quot; To make your own blank copy of the spreadsheet I use below, check out the &lt;a href=&quot;https://docs.google.com/spreadsheets/d/1eWaO_8pOdC7QwN4umnRnniEVFECMUc1b42FA3Ea7D0c/edit?usp=sharing&quot;&gt;Taxonomy Manager Google Sheets template here&lt;/a&gt;.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/9c314f25d5875dbed68100e0a8215be5b01fd7b6-3026x1722.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;683&quot; alt=&quot;A spreadsheet showing a hierarchical organization of terms and term definitions associated with each.&quot; /&gt;&lt;figcaption&gt;Candidate taxonomy terms, relationships, and definitions in the template worksheet&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;To get my candidate terms into the template, I highlight the relevant set of &amp;quot;sticky notes&amp;quot; in Miro and paste them into the first column. I then organize them into the intended hierarchy and use a &lt;code&gt;VLOOKUP()&lt;/code&gt; function in the &amp;quot;Definitions&amp;quot; column to bring over generated definitions from the &amp;quot;Processed Tags&amp;quot; sheet:&lt;/p&gt;&lt;pre&gt;&lt;code&gt;=VLOOKUP(C5,&apos;Processed Tags&apos;!A$2:G$39,7,FALSE)&lt;/code&gt;&lt;/pre&gt;&lt;p&gt;🚨 Do not take these definitions at face value! 🚨 &lt;/p&gt;&lt;p&gt;Review, vet, and refine the LLM-generated definitions, and create definitions for any terms you added in the sketching phase. While it&amp;#x27;s possible to outsource this step to an LLM, the mental activity of creating definitions for this context is a powerful tool for vetting and refining your structure. I find that defining the terms also helps me spot inconsistencies and iterate on the draft approach to create a stronger, more cohesive whole.&lt;/p&gt;&lt;p&gt;This is also a step where, if I&amp;#x27;m working with project stakeholders and collaborators, I&amp;#x27;ll meet with them to get their feedback and input. Even if you&amp;#x27;re working alone, however, careful attention to the definition phase can help you avoid frustrating errors.&lt;/p&gt;&lt;h2 id=&quot;vet-the-proposed-structure&quot;&gt;Vet the Proposed Structure&lt;/h2&gt;&lt;p&gt;Once you have a revised structure that is coherent, internally consistent, and representative of your goals, test it out against your use cases. As with previous steps, if you&amp;#x27;re working on a large taxonomy with multiple stakeholders, there are time-tested approaches for getting feedback at scale. Closed card sorting and tree testing are both excellent methods for vetting that a proposed structure is consistent with intended users&amp;#x27; mental models.&lt;/p&gt;&lt;p&gt;At a small scale, manual approaches to vetting a structure against use cases can provide an effective sanity check. For the topic taxonomy discussed here, I pulled five recent articles from my website, tagged them with terms from the proposed taxonomy draft, and then traced the connections between the assigned tags based on the association rules outlined in my use cases.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/5eedb962e760ebdf3a0ede5455244781c0efc302-3340x2808.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;1009&quot; alt=&quot;A virtual whiteboard display of six article previews &amp;quot;tagged&amp;quot; with term sticky notes, and &amp;quot;related&amp;quot; with colored arrows. Expected &amp;quot;related articles&amp;quot; recommendations are listed next to each. &quot; /&gt;&lt;figcaption&gt;Test articles manually tagged with candidate terms&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;For this exercise, I drew red connectors for tag-to-tag matches and orange connectors for sibling matches. Solid lines represent connections between the first three ranked tags; dashed lines are connections to a lower-priority (less relevant) tag. The result is messy, but it&amp;#x27;s fast and helps you understand what results your proposed rules and structure will create.&lt;/p&gt;&lt;p&gt;Showing these connections and weights visually allows me to approximate which related articles the tags assigned to a given piece of content are likely to produce. If these are the relationships I expect—or what I would suggest if I were manually connecting content—I&amp;#x27;m likely on the right track. If not, I&amp;#x27;ll return to the model and look for sources of the mismatch.&lt;/p&gt;&lt;p&gt;This is another instance where if you&amp;#x27;re working with stakeholders or subject matter experts, you&amp;#x27;ll want to involve them in reviewing, validating, and nuance these findings.&lt;/p&gt;&lt;h2 id=&quot;migrate-to-the-cms&quot;&gt;Migrate to the CMS&lt;/h2&gt;&lt;p&gt;Now that I&amp;#x27;ve vetted my terms and structure against my use cases and mocked up a sample tagging scenario, I can be reasonably confident that the taxonomy I&amp;#x27;ve created will support the goals I defined at the outset. The true test of a plan, however, is contact with the real world: It&amp;#x27;s time to migrate the taxonomy to my content management system.&lt;/p&gt;&lt;p&gt;For any but the smallest taxonomies, manually migrating terms can be a tedious and error-prone process. Fortunately, if you&amp;#x27;ve followed a standardized process in creating your structure, migrating terms and relationships to a standards-compliant taxonomy management tool needn&amp;#x27;t be an ordeal&lt;/p&gt;&lt;p&gt;The spreadsheet template I used to create the topic taxonomy above adheres to the &lt;a href=&quot;https://www.w3.org/TR/skos-reference/&quot;&gt;Simple Knowledge Organization System (SKOS)&lt;/a&gt; standard established by the World Wide Web Commission (W3C). The taxonomy management tool to which I&amp;#x27;ll be migrating, the &lt;a href=&quot;https://www.sanity.io/plugins/taxonomy-manager&quot;&gt;Sanity Studio Taxonomy Manager&lt;/a&gt; plug-in (which, coincidentally, I built and maintain), is also SKOS compliant. Thanks to Sanity.io&amp;#x27;s integration-friendly content store, I can map and upload the entire taxonomy with a single node.js script.&lt;/p&gt;&lt;p&gt;For those of you already using Sanity, I&amp;#x27;ll share more details on using this script in a follow-up post. If you&amp;#x27;re using a different CMS—or are evaluating tech stack options—it&amp;#x27;s well worth researching the degree to which your tools support open standards and free movement between platforms. Just as your taxonomy should be structured (and sized) to support goals that meet clearly defined outcomes, the tools you use to deploy and govern that taxonomy should likewise be chosen to support its scale and interoperability requirements.&lt;/p&gt;&lt;p&gt;Once your taxonomy is integrated with your CMS, the next step, of course, is to start tagging content. In a future post I&amp;#x27;ll explore some ways you can (responsibly) use LLMs to help with that. I&amp;#x27;ll also discuss how your structure and term definitions (you &lt;em&gt;are&lt;/em&gt; defining your terms, right? 🧐) can help you create consistent, reliable results using purposefully coordinated, resource-appropriate models.&lt;/p&gt;</content>
  </entry>
  <entry>
    <title type="text">AI Supported Taxonomy Term Generation</title>
    <link rel="alternate" type="text/html" href="https://preview.andyfitzgeraldconsulting.com/insights/ai-taxonomy-term-generation/"/>
    <id>https://preview.andyfitzgeraldconsulting.com/insights/ai-taxonomy-term-generation/</id>
    <published>2025-01-15T00:00:00Z</published>
    <updated>2025-01-15T00:00:00Z</updated>
    <summary type="text">An example workflow for coordinating LLMs and text analytics to generate topic tags for an article collection.</summary>
    <category term="Method"/>
    <category term="Taxonomy"/>
    <category term="AI Integration"/>
    <category term="Python"/>
    <content type="html">&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/b20d2045c9b611e76678883e7cecf66196ec4ad8-3573x2311.png?rect=0,186,3573,2010&amp;amp;w=1200&amp;amp;h=675&amp;amp;fit=crop&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;675&quot; alt=&quot;Diamond patterned wire fence with small circular metal tags printed with names hanging from each vertice&quot; /&gt;&lt;/figure&gt;&lt;p&gt;Underneath the hype and hyperbole of &amp;quot;AI&amp;quot; capabilities, there&amp;#x27;s a compelling use case for responsibly using LLMs to help information architecture practitioners make better use of time-tested analysis and classification approaches and tools. Here is an example of one way that LLMs and rules-based text analysis techniques can be coordinated to generate tags for a topic taxonomy that has fallen out of sync with its content set. &lt;/p&gt;&lt;p&gt;Slowly but surely, &amp;quot;AI&amp;quot; in the form of large language models (LLMs) is becoming a part of my information architecture toolkit. As I&amp;#x27;ve &lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/insights/deskilling-large-language-models/&quot;&gt;written about elsewhere&lt;/a&gt;, I find they&amp;#x27;re most useful for the kind of IA work I do for my clients when scoped to narrow, specific tasks, often in a workflow with other natural language processing, logic-based reasoning, and human evaluation steps.&lt;/p&gt;&lt;p&gt;A recent experiment I conducted with my consulting website provides an example of what this can look like in practice. Like many websites that have been around for more than a few years (and that may or may not be guilty of a lack of diligence with their governance process 😬), I found that the terms in my topic taxonomy had fallen out of sync with the kinds of topics I now write about.&lt;/p&gt;&lt;p&gt;I &lt;em&gt;could&lt;/em&gt; re-read all of my articles, posts, and case studies and manually generate a revised list of candidate topic tags. I have just enough content, however, to make the prospect of going through it piece by piece daunting. I likewise don&amp;#x27;t sufficiently trust any of the current generation of language models (or &amp;quot;graph rag&amp;quot; systems) to capture the user, content, and business aspects of my taxonomy needs to hand over the task wholesale.&lt;/p&gt;&lt;p&gt;Properly guided and supervised, however, an LLM can be one element of a coordinated toolchain for this task. This article is a walkthrough of one way that chain can be assembled. What follows is a look at:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;information design considerations for toolchain steps&lt;/li&gt;&lt;li&gt;key toolchain tasks&lt;/li&gt;&lt;li&gt;results produced &amp;amp; next steps&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;👉 View the &lt;a href=&quot;https://github.com/andybywire/tag-gen&quot;&gt;full repo for this workflow on GitHub&lt;/a&gt;.&lt;/p&gt;&lt;h2 id=&quot;goal&quot;&gt;Goal&lt;/h2&gt;&lt;p&gt;The goal of this workflow is &lt;em&gt;not&lt;/em&gt; to tag content. Free-tagging content and tagging content with existing taxonomy terms are workflows that have already gotten a lot of attention, and there are alreacy many excellent examples of how to accomplish this out there.&lt;/p&gt;&lt;p&gt;I also don&amp;#x27;t want an LLM to generate a taxonomy &lt;em&gt;for&lt;/em&gt; me. A well-designed taxonomy affords a nuanced expression of user needs, business goals, and content focus in a specific context. This requires judgment and accountability. LLMs are notorious for providing answers that &lt;em&gt;look&lt;/em&gt; right, but may or may not be garbage. As taxonomists &lt;a href=&quot;https://conferences.infotoday.com/documents/458/1215_Moore.pdf&quot;&gt;Shannon Moore and Max Gaibort from Electronic Arts&lt;/a&gt; so aptly put it in their presentation at &lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/insights/taxonomy-boot-camp-2024-themes-takeaways/&quot;&gt;Taxonomy Boot Camp&lt;/a&gt; in 2024, &amp;quot;taxonomy-shaped responses are not a taxonomy.&amp;quot;&lt;/p&gt;&lt;p&gt;I do, however, want a qualified set of candidate terms that &lt;em&gt;could&lt;/em&gt; work as entries in my revised taxonomy. &amp;quot;Qualified,&amp;quot; in this sense, means those terms that have relevance to my users, content, and business goals (&amp;quot;warrants&amp;quot; in taxonomy lingo), and those that are sufficiently represented across my content collection that they will work to coordinate resources. A tag that only appears once—or can be applied to &lt;em&gt;every&lt;/em&gt; resource—is not helpful for discovery, recommendation, or analytics.&lt;/p&gt;&lt;p&gt;A qualified candidate tag should also include a definition and a context-sensitive rationale for why it applies to a particular resource. It should also only occur once in the proposed candidate terms list. This will give the eventual taxonomist (i.e. me) a set of useful inputs with which to make informed decisions about if and how a candidate term fits into the final revised taxonomy.&lt;/p&gt;&lt;h2 id=&quot;workflow-steps&quot;&gt;Workflow Steps&lt;/h2&gt;&lt;p&gt;An LLM is clearly a good fit for some of the goals defined above ... and would clearly be rubbish (or wantonly wasteful) for others. I also don&amp;#x27;t need the same &amp;quot;strength&amp;quot; of LLM for each generative task. Here&amp;#x27;s the approach I took to coordinate constituent steps so that each is completed with the best tool for the job.&lt;/p&gt;&lt;p&gt;👉 Follow along in the &lt;a href=&quot;https://github.com/andybywire/tag-gen/blob/main/tag_generator.ipynb&quot;&gt;full Notebook here&lt;/a&gt;.&lt;/p&gt;&lt;h3 id=&quot;1-fetch-tidy-articles&quot;&gt;1. Fetch &amp;amp; Tidy Articles&lt;/h3&gt;&lt;p&gt;I start by querying my CMS (built with &lt;a href=&quot;https://www.sanity.io/&quot;&gt;Sanity&lt;/a&gt;) for the relevant set of articles that should inform my generated tags. Sanity&amp;#x27;s &amp;quot;projections&amp;quot; allow me to return just the data I need and format keys to values that will be easy to reference later on.&lt;/p&gt;&lt;p&gt;In this GROQ query, for example, &lt;code&gt;type&lt;/code&gt; (sans underscore) is a reference to a term in my site&amp;#x27;s &amp;quot;types&amp;quot; taxonomy. The GROQ dereferencing operator (&lt;code&gt;-&amp;gt;&lt;/code&gt;) allows me to return just the preferred label for that term.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/82b2b00ea1f281668748e3500061565851a4fae6-1236x628.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;610&quot; alt=&quot;A response variable assigned to the output of a post request generated with the POST method. The query returns the title, URL, and type of each document of type &amp;quot;Article&amp;quot; or &amp;quot;Case Study&amp;quot;&quot; /&gt;&lt;figcaption&gt;A simple GROQ query for &amp;quot;article&amp;quot; and &amp;quot;case study&amp;quot; content types&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;I use &lt;a href=&quot;https://beautiful-soup-4.readthedocs.io/en/latest/&quot;&gt;Beautiful Soup&lt;/a&gt; to strip out decorative headers, timestamps, and existing lists of tags and topics from the returned results. I then convert the HTML to Markdown to make it easier for the LLM to process. This gives the language model a representation similar to what site visitors see when visiting article pages.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/7b7ee65fbb560296cd8da7651b035a009be8951a-1164x1318.png?w=1164&amp;amp;auto=format&quot; width=&quot;1164&quot; height=&quot;1318&quot; alt=&quot;A Python `for` loop that removes topic tags, decorative headers, and timestamps from article HTML code. The resulting code is subsequently transformed into Markdown. &quot; /&gt;&lt;figcaption&gt;Removing existing tags with Beautiful Soup and converting to Markdown&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;All of this content is then added to a Pandas DataFrame. I also add in the word count of each final article, which I&amp;#x27;ll use later to determine a range for the number of tags the LLM should produce.&lt;/p&gt;&lt;h3 id=&quot;2-create-topic-tag-generation-prompts&quot;&gt;2. Create Topic Tag Generation Prompts&lt;/h3&gt;&lt;p&gt;Now that I&amp;#x27;ve got the content data I need an accessible format, it&amp;#x27;s time to give the LLM some guidance. I don&amp;#x27;t want it to &amp;quot;free tag&amp;quot; this content in the broad sense of the term. My site has a narrow purpose and is intended to speak to a specific audience. I want the LLM to take that into account.&lt;/p&gt;&lt;p&gt;I accomplish this with a system prompt structured into five sections (&lt;a href=&quot;https://github.com/andybywire/tag-gen/blob/main/tag_generator.ipynb&quot;&gt;see the full prompts in the Jupyter Notebook&lt;/a&gt;):&lt;/p&gt;&lt;ol&gt;&lt;li&gt;A general overview of what the requested task is and what it will accomplish&lt;/li&gt;&lt;li&gt;A statement about the purpose of the AF Consulting website&lt;/li&gt;&lt;li&gt;A concise set of target audience profiles&lt;/li&gt;&lt;li&gt;The article to be tagged&lt;/li&gt;&lt;li&gt;A statement describing the grammatical, orthographic, and metadata structure of the tags to be returned&lt;/li&gt;&lt;/ol&gt;&lt;p&gt;Because this is a relatively complex task with a fairly large input, I&amp;#x27;ve opted for a hosted LLM to carry it out (GPT 4o-mini). For consistency, I also want a model that can enforce structured output. In this case, the model will return a Python dictionary with each output element stored as a value in a predefined structure that I can easily iterate over later.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/db622c5de85aa5d51b3ff11b505e0da16d6b7553-1228x1140.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;1114&quot; alt=&quot;A Pydantic class specifying that the generated tag output should be returned as a set of keys with names: tag, explanation, and relevance. &quot; /&gt;&lt;figcaption&gt;The structured output definition for the LLM tag generation task. &lt;/figcaption&gt;&lt;/figure&gt;&lt;h3 id=&quot;3-generate-tags&quot;&gt;3. Generate Tags&lt;/h3&gt;&lt;p&gt;To generate tags, I loop through the article content in the &amp;quot;articles&amp;quot; DataFrame and submit each with the above prompt to the language model. This step is also where I adjust the number of tags requested based on the length of the article:&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/5560b11cea7525cedebf49e358cf3f99560af4e8-1170x166.png?w=1170&amp;amp;auto=format&quot; width=&quot;1170&quot; height=&quot;166&quot; alt=&quot;An expression setting the count variable to 10 - 20 tags, depending on the length of the article&quot; /&gt;&lt;figcaption&gt;The LLM should return 10 - 20 tags, depending on the length of the article&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;To be clear, 10 - 20 tags are far too many tags for any single article. Just as I would request of a human tagger, however, I want the model to exhaust the &amp;quot;obvious&amp;quot; tags and dig for potential outliers. Most of these will be thrown out, but by collecting and reviewing them, I keep the process open to serendipity and the discovery of new ways to describe existing content—or new angles to explore in future articles.&lt;/p&gt;&lt;p&gt;After this expansive pass of tags is generated, I export it as a &lt;code&gt;.csv&lt;/code&gt;. This allows me to reuse a copy of this step&amp;#x27;s output if I need to iterate subsequent steps (and saves on the resource consumption associated with a hosted LLM). It also provides a reference output for the taxonomy authoring work that comes in the next step.&lt;/p&gt;&lt;h3 id=&quot;4-process-tag-list&quot;&gt;4. Process Tag List&lt;/h3&gt;&lt;p&gt;Though useful to generate, the broad take on topic tags generated in the previous step is not the primary input I want to work with when I take a first pass at deciding which tags should be included in the revised taxonomy. Because I&amp;#x27;ve also collected &amp;quot;relevance&amp;quot; scores along the way, I can use this value to filter out low relevance tags that only occur once:&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/d4aecbcb4f488746f36b8f0a2e220e400091da5e-1238x252.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;244&quot; alt=&quot;A filter method with a lambda function that only includes tags with an article count of more than one and a relevance score greater than 0.6&quot; /&gt;&lt;figcaption&gt;Singleton and low-relevance tags are removed from the filtered set&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;Low-relevance tags that occur in multiple places may have a story to tell, so I&amp;#x27;ll leave those be.&lt;/p&gt;&lt;p&gt;This step is also where I combine duplicate entries. As you&amp;#x27;d imagine, &amp;quot;information architecture&amp;quot; and &amp;quot;content strategy&amp;quot; occur more than once. When deduplicating tags I also calculate a set of stats from the set:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;number of resources tagged&lt;/li&gt;&lt;li&gt;average &amp;quot;relevance&amp;quot; score&lt;/li&gt;&lt;li&gt;standard deviation of relevance scores&lt;/li&gt;&lt;li&gt;number of content types represented&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;These numbers help me understand at a glance how a particular tag fits with the content set as a whole. I also join together all of the definitions provided (I&amp;#x27;ll synthesize them in the next step).&lt;/p&gt;&lt;h3 id=&quot;5-synthesize-definitions&quot;&gt;5. Synthesize Definitions&lt;/h3&gt;&lt;p&gt;Tidying up the concatenated list of definitions created in the last step is another task well-suited to an LLM. Condensing and summarizing verbose content is an area where language models excel—and where humans quickly go crosseyed from the tedium of the work.&lt;/p&gt;&lt;p&gt;This step does not, however, require a high-power hosted LLM. Most of the concatenated definitions are not very long and they mostly repeat the same ideas. By using a smaller model hosted on my MacBook Pro, I can keep the cost and the resource impact of using an LLM to a minimum.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/34de57cc410157924d718c00c49b498647bf00cd-1234x1670.png?rect=0,0,1234,1560&amp;amp;w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;1517&quot; alt=&quot;An LLM prompt instructing the model to synthesize long, repetitive definitions into a single concise definition. &quot; /&gt;&lt;figcaption&gt;The definition synthesis prompt and loop&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;Synthesized definitions are added to a new column in the DataFrame. Unchanged definitions (i.e. for single-entry tags) are passed through to this column for consistency. I then export the trimmed, processed, and synthesized tags as a second &lt;code&gt;.csv&lt;/code&gt; for taxonomy development. If anything looks fishy in these final results, I can always refer to the full tag list exported in step three to compare individual entries.&lt;/p&gt;&lt;h3 id=&quot;6-visualize-results&quot;&gt;6. Visualize Results&lt;/h3&gt;&lt;p&gt;This step isn&amp;#x27;t strictly necessary, but it&amp;#x27;s a satisfying wrap-up for the workflow—and the visual representation offers a novel perspective on the generated tag collection as a whole.&lt;/p&gt;&lt;p&gt;For this dataset I&amp;#x27;ve configured a plot to show resource count and relevance score on the x-y axis and standard deviation as a color gradient. The standard deviation metric allows me to quickly identify tags that have the same—or very different—relevance to their respective articles. The size of the point shows the number of content types represented by each tag. Additional data point details are available on hover.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/8615fdd808131caf62b389d5e5b88c42ea441c55-1566x1540.png?rect=0,5,1566,1535&amp;amp;w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;1176&quot; alt=&quot;A plot with &amp;quot;number of resources&amp;quot; on the y axis and &amp;quot;relevance score&amp;quot; on the x axis. A color scale indicates the standard deviation of relevance values for each point.&quot; /&gt;&lt;figcaption&gt;An interactive plot helps visualize generated results&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;By exporting this final plot as an HTML file, I can preserve the interactive features for later reference. &lt;/p&gt;&lt;h2 id=&quot;results-next-steps&quot;&gt;Results &amp;amp; Next Steps&lt;/h2&gt;&lt;p&gt;If you&amp;#x27;ve grown accustomed to the &amp;quot;LLM as one-stop-shop&amp;quot; narratives that often play out on social media, you might be underwhelmed by the output of this process: two &lt;code&gt;.csv&lt;/code&gt; files and an interactive chart.&lt;/p&gt;&lt;p&gt;Please recall, however, that the goal of this workflow isn&amp;#x27;t to create a taxonomy—or attempt to reproduce the judgment calls made by a skilled taxonomist. The goal is to provide a taxonomist with &lt;em&gt;some&lt;/em&gt; of the input they need to create an effective vocabulary and help them (in this case, me) minimize the slog of manually reviewing material, exhausting tag options, and defining and rationalizing each candidate tag.&lt;/p&gt;&lt;p&gt;By importing the exported &lt;code&gt;.csv&lt;/code&gt; documents into a spreadsheet (taxonomy&amp;#x27;s natural spawning ground), I&amp;#x27;ve got an informed and annotated set of candidate terms in the environment in which taxonomies invariably take initial shape.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/99372cfc2205ff66ce2c4fdab8af76584e3496c4-2844x1778.png?rect=0,0,2844,1774&amp;amp;w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;749&quot; alt=&quot;A spreadsheet with a list of recommended tags in the left column, conditionally highlighted statistics in the next three columns, and synthesized definitions for each&quot; /&gt;&lt;figcaption&gt;Light conditional formatting highlights patterns in tag results&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;I&amp;#x27;m able to quickly see, for instance, which tags are applicable to a majority of my content. I may consider these as top level terms—or may opt to exclude them altogether if they don&amp;#x27;t do any work to differentiate topics.&lt;/p&gt;&lt;p&gt;The standard deviation of relevance scores likewise helps me identify which tags may have different &amp;quot;strengths&amp;quot; in relation to a given article. In some cases, a parent term may be a better fit. This will inform the structure of the eventual hierarchy.&lt;/p&gt;&lt;p&gt;In the &amp;quot;Raw Tags&amp;quot; tab I can also see which articles had the most &amp;quot;rejected&amp;quot; tags. In this case, that was &amp;quot;&lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/insights/cognitive-science-for-designers/&quot;&gt;A Cognitive Sciences Reading List for Designers&lt;/a&gt;,&amp;quot; which makes sense as this post covers a dozen topics that inform my practice but which aren&amp;#x27;t a focus of it.&lt;/p&gt;&lt;p&gt;In a broad sense, these results provide data for an informed revision process that can take shape based on the needs of a particular project. If you&amp;#x27;re creating a completely new structure, for example, a card sorting exercise with candidate terms may be the right next move. If you&amp;#x27;re fitting revised terms into an existing structure, drafting the revision based on defined use cases and then tree testing with users might be the right follow-on step.&lt;/p&gt;&lt;p&gt;For this taxonomy, I&amp;#x27;ll continue with the latter of these two options. I&amp;#x27;ll discuss my process for that work and for migrating it back into my CMS in a follow-up post. If that piques your interest, stay tuned!&lt;/p&gt;</content>
  </entry>
  <entry>
    <title type="text">Taxonomy Boot Camp 2024 Themes &amp; Takeaways</title>
    <link rel="alternate" type="text/html" href="https://preview.andyfitzgeraldconsulting.com/insights/taxonomy-boot-camp-2024-themes-takeaways/"/>
    <id>https://preview.andyfitzgeraldconsulting.com/insights/taxonomy-boot-camp-2024-themes-takeaways/</id>
    <published>2024-12-04T00:00:00Z</published>
    <updated>2024-12-04T00:00:00Z</updated>
    <summary type="text">Summary of the top themes and insights from the 2024 Taxonomy Boot Camp conference in Washington DC.</summary>
    <category term="Conference Themes"/>
    <category term="Taxonomy"/>
    <category term="Systems Thinking"/>
    <category term="AI Integration"/>
    <content type="html">&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/b9e70f0776c4d61c656fc5fd8fb74558feb55c78-3024x4032.jpg?rect=190,785,2604,1465&amp;amp;w=1200&amp;amp;h=675&amp;amp;fit=crop&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;675&quot; alt=&quot;Image of the DC metro map, centered on Federal Triangle and the National Mall&quot; /&gt;&lt;/figure&gt;&lt;p&gt;Two weeks ago it was again my pleasure and privilege to attend Taxonomy Boot Camp (TBC) in Washington, DC. This was TBC&amp;#x27;s 20th year, and, in the four times I&amp;#x27;ve attended since 2016, was the strongest argument yet for the enduring importance of well-designed and integrated taxonomies. In addition to tracks for &amp;quot;taxonomy fundamentals,&amp;quot; this year&amp;#x27;s event featured tracks for &amp;quot;taxonomy applications,&amp;quot; &amp;quot;taxonomy operations,&amp;quot; and &amp;quot;advanced data and semantic layers.&amp;quot; This is my roundup of the themes and insights that stood out to me most.&lt;/p&gt;&lt;p&gt;Two weeks ago it was again my pleasure and privilege to attend &lt;a href=&quot;https://www.taxonomybootcamp.com/&quot;&gt;Taxonomy Boot Camp&lt;/a&gt; (TBC) in Washington, DC. This was TBC&amp;#x27;s 20th year, and, in the four times I&amp;#x27;ve attended since 2016, was the strongest argument yet for the enduring importance of well-designed and integrated taxonomies. &lt;/p&gt;&lt;p&gt;For those who have not had a chance to attend TBC, the &amp;quot;Boot Camp&amp;quot; title may sell the range of content covered short. In addition to tracks for &amp;quot;taxonomy fundamentals,&amp;quot; this year&amp;#x27;s event also featured tracks for taxonomy applications, taxonomy operations, and advanced data and semantic layers. If that sounds like a lot of content ... it was! &lt;/p&gt;&lt;p&gt;Here is a roundup of the top themes and insights I took away from the sessions I attended. Many speakers have shared their slides and TBC has graciously made these available for anyone to download, so I’ve included links to decks where available. You can &lt;a href=&quot;https://www.taxonomybootcamp.com/2024/Presentations.aspx&quot;&gt;access the whole list here&lt;/a&gt;.&lt;/p&gt;&lt;h2 id=&quot;1-taxonomy-context&quot;&gt;1. Taxonomy = Context&lt;/h2&gt;&lt;p&gt;The most typical use of taxonomy is, arguably, to provide real-world context and meaning to collections of data. Taxonomies capture the domain-specific ways classes of instances relate and express those relationships in machine- and human-readable ways. This context is a critical element for &amp;quot;bigger picture&amp;quot; findability, discovery, and understanding.&lt;/p&gt;&lt;p&gt;Joseph Busch presented a spot-on example of this use case in a study of a taxonomy project his firm, Taxonomy Strategies, performed on a huge set of government archives. In order to identify the correct attributes to make this content findable to the 3,000 employees who potentially needed access to it, Busch and team identified use cases for all the document types—which included architectural plans, binders, aperture cards, and more—and then identified the attributes that needed to be present to support those use cases. This taxonomy became the standard specification used by the company that did the work of digitizing the records.&lt;/p&gt;&lt;p&gt;Similarly, Richard Huffine, Assistant Director of Enterprise Information &amp;amp; Records at the FDIC, presented a case study of a Data Catalog project he undertook with the help of Holly Maykow and Madeleine Adamec, both consultants with the firm Enterprise Knowledge. Similarly to the Taxonomy Strategies study above, the crucial element of the work at the FDIC wasn&amp;#x27;t so much technical as it was semantic: getting the metadata profile right was key. This was the FDIC&amp;#x27;s &lt;em&gt;third&lt;/em&gt; attempt to bring a data catalog online, so the focus on the semantics (as opposed to just the technology) was a lesson they learned through direct experience.&lt;/p&gt;&lt;p&gt;&lt;strong&gt;Talks&lt;/strong&gt;&lt;/p&gt;&lt;ul&gt;&lt;li&gt;&lt;a href=&quot;https://conferences.infotoday.com/documents/458/1015_Busch.pptx&quot;&gt;Using Taxonomy to Move From Paper to Knowledge Graph&lt;/a&gt;, Joseph Busch, Taxonomy Strategies&lt;/li&gt;&lt;li&gt;&lt;a href=&quot;https://conferences.infotoday.com/documents/458/1100_Huffine.pdf&quot;&gt;Mastering Metadata With a Data Catalog&lt;/a&gt;, Richard Huffine, FDIC &amp;amp; X &amp;amp; Y from Enterprise Knowledge&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;&lt;strong&gt;Bonus Content:&lt;/strong&gt; Michele Ann Jenkins and Katherine Black from Dovecot Studio have shared the deck from their &lt;a href=&quot;https://conferences.infotoday.com/documents/458/1400_Jenkins.pdf&quot;&gt;Taxonomy 101&lt;/a&gt; workshop. I was moderating the Taxonomy Applications track at the time so couldn&amp;#x27;t look in, but their deck is a fantastic resource for folks getting started in taxonomy development—or looking for ways to improve an existing taxonomy. &lt;/p&gt;&lt;h2 id=&quot;2-embedding-taxonomy-across-the-organization&quot;&gt;2. Embedding Taxonomy Across the Organization&lt;/h2&gt;&lt;p&gt;While many taxonomists, I suspect, would be perfectly happy immersed in a heads-down world of fine-tuning, measuring, and iterating terms and relationships, this (sadly) isn&amp;#x27;t a good strategy for helping an organization get the most of their taxonomy efforts. Several presenters this year spoke directly to the challenges of making taxonomy &amp;quot;stick&amp;quot; in an organization and presented strategies for helping professional peers and colleagues see (and benefit from) the value of taxonomy work. &lt;/p&gt;&lt;p&gt;Ahren Lehnert, Principal Taxonomist at Nike, emphasized that advocating for taxonomy integration requires a &lt;em&gt;vocal &lt;/em&gt;and&lt;em&gt; sustained&lt;/em&gt; communication effort. Lehnert also recommends positioning taxonomy as a necessity (even a dependency) for projects. One does this, he says, by not only communicating what taxonomy &lt;em&gt;is&lt;/em&gt;, but what it &lt;em&gt;does &lt;/em&gt;for folks: how taxonomy makes their lives and work easier. We already know this as taxonomists, of course, but it is often far from obvious to our colleagues and collaborators. &lt;/p&gt;&lt;p&gt;In her rich talk on best practices for the solo taxonomist, Bonnie Griffin, a taxonomy consultant with Enterprise Knowledge, amplified the message of communicating the benefits of taxonomy work clearly, early, often, and &lt;em&gt;loudly&lt;/em&gt;. Some of my favorite tips:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;find someone who can echo you, who can repeat your ideas as well as you can—and encourage them&lt;/li&gt;&lt;li&gt;help people understand that working with you will make them look good&lt;/li&gt;&lt;li&gt;provide different options for how to work, with different levels of value for different levels of involvement&lt;/li&gt;&lt;li&gt;don&amp;#x27;t just say that AI can be improved by taxonomy; show that that&amp;#x27;s the case (for example, tagging risky content can identify risky content to &lt;em&gt;exclude &lt;/em&gt;from RAG responses)&lt;/li&gt;&lt;li&gt;communicate &lt;em&gt;early and often&lt;/em&gt; that taxonomy work is never done&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;In a Q&amp;amp;A exchange after her talk, Griffin recommended a strategy for showing that taxonomy work is never actually &amp;quot;finished&amp;quot;: find a use case in the organization where things change a lot, and in which it would be embarrassing not to reflect those changes. The talk following hers, by two speakers from game company Electronic Arts, offered a pithy example: patterns of game player language are constantly evolving. Tracking and reflecting those changes in the interface can help players engage in and discover new content on their own terms.&lt;/p&gt;&lt;p&gt;&lt;strong&gt;Talks&lt;/strong&gt;&lt;/p&gt;&lt;ul&gt;&lt;li&gt;&lt;a href=&quot;https://conferences.infotoday.com/documents/458/1400_Lehnert.pdf&quot;&gt;Stand Still Like the Hummingbird: Enterprise Taxonomy Strategy When Nothing Stands Still&lt;/a&gt;, Ahren Lehnert, Nike&lt;/li&gt;&lt;li&gt;&lt;a href=&quot;https://conferences.infotoday.com/documents/458/1145_Griffin.pptx&quot;&gt;Consulting From Within: Best Practices for the Solo Taxonomist&lt;/a&gt;, Bonnie Griffin, Enterprise Knowledge&lt;/li&gt;&lt;/ul&gt;&lt;h2 id=&quot;3-the-role-of-ai-in-taxonomy-design&quot;&gt;3. The Role of AI in Taxonomy Design&lt;/h2&gt;&lt;p&gt;Weirdly, there were &lt;em&gt;no&lt;/em&gt; talks about AI related to taxonomy design. &lt;/p&gt;&lt;p&gt;LOL ... As if, right?&lt;/p&gt;&lt;p&gt;Refreshingly, talks that had AI elements were much more balanced and focused on lessons learned than the breathless AI hype so common for the last couple years. Presenters also moved past the fantasy that AI can &amp;quot;do all the things,&amp;quot; and instead focused on a few explicit places &amp;quot;AI&amp;quot; (or, more properly, language models) can help: filling in for tedious tasks, augmenting human-led work, and expanding capabilities to outcomes that were simply not possible before.&lt;/p&gt;&lt;h3 id=&quot;ai-for-tedious-tasks&quot;&gt;AI for Tedious Tasks&lt;/h3&gt;&lt;p&gt;Getting AI to help out with the repetitive tasks humans would rather pass on was the focus of my talk at this year&amp;#x27;s Boot Camp. I presented an example and a set of heuristics for &amp;quot;deskilling&amp;quot; language models to make them more consistent and more reliable for taxonomy&amp;#x27;s more mundane, mind-numbing slog work. I offered that by paying close attention to the composition, granularity, and observability of language model orchestration, we can use AI to accomplish the kinds of tasks we traditionally outsource to press-ganged client teams or grad students. &lt;/p&gt;&lt;h3 id=&quot;ai-for-augmenting-human-led-work&quot;&gt;AI for Augmenting Human-Led Work&lt;/h3&gt;&lt;p&gt;In addition to using AI to do work most humans would rather avoid in the first place, several presentations focused on ways to use language models to increase productivity and jump-start taxonomy projects. Rachael Maddison, a product manager with Adobe&amp;#x27;s Taxonomy as a Service Platform, gave a demonstration of how they&amp;#x27;re using AI in their &amp;quot;MetaHealth&amp;quot; content audit tools to dramatically improve tagging and targeting productivity for content creators (in one case measuring a 75% increase!).&lt;/p&gt;&lt;p&gt;Shannon Moore and Max Gaibort, taxonomists with Electronic Arts (EA), presented a case study of how they worked with EA&amp;#x27;s data science team to dramatically cut the time it takes to create new taxonomy terms from data in logs and customer support channels. By training an LLM to match candidate terms to their existing taxonomy, they were able to narrow 2,400 candidate terms down to 500. They emphasize, however, that human review remains essential. Sometimes the answers the model gave looked right, but didn&amp;#x27;t stand up to professional scrutiny. As Moore and Gaibort put it, &amp;quot;taxonomy shaped responses are not a taxonomy.&amp;quot; &lt;/p&gt;&lt;p&gt;For a broader view of getting started with AI for taxonomy task augmentation, IA consultants Erik Lee from Factor Firm and Michele Ann Jenkins from Dovecot Studio presented a joint session on AI approaches to taxonomy and tagging. Their decks are full of valuable pointers and best practices. Perhaps my favorite takeaway was Jenkins&amp;#x27;s point that &amp;quot;for most projects, the net number of people you need won&amp;#x27;t go down — they&amp;#x27;ll just be able to focus on things that &lt;em&gt;people&lt;/em&gt; are best at doing.&amp;quot;&lt;/p&gt;&lt;h3 id=&quot;ai-that-expands-human-capabilities&quot;&gt;AI that Expands Human Capabilities&lt;/h3&gt;&lt;p&gt;Like many folks in my professional circle, I&amp;#x27;m a cautiously optimistic skeptic about the degrees to which language models might improve the work we do as knowledge professionals. Most of the benefits I&amp;#x27;ve seen have, when put to the test of real world data and business conditions, shown incremental improvements over current practice. Benefits, to be sure, but benefits that should be carefully weighed against the ecological and human costs of the &amp;quot;AI&amp;quot; industry.&lt;/p&gt;&lt;p&gt;Unanimous.ai CEO Louis Rosenberg&amp;#x27;s opening keynote of TBC day two, however, showed me a language model application that stood out as categorically different than anything I&amp;#x27;d ever seen. Unanimous.ai&amp;#x27;s Thinkscape application uses language models to orchestrate real-time large-scale conversations &lt;em&gt;among people, &lt;/em&gt;bridging two otherwise intractable conversation barriers: humans can&amp;#x27;t &amp;quot;converse&amp;quot; in large groups, and humans can&amp;#x27;t participate in multiple conversations at once. &lt;/p&gt;&lt;p&gt;According to Rosenberg, the tool his company is building doesn&amp;#x27;t replace human intelligence; it channels it to support collective decision-making. Rosenberg notes that &amp;quot;people aren&amp;#x27;t data points; they are data processors.&amp;quot; Thinkscape extends this processing capacity.&lt;/p&gt;&lt;p&gt;Rosenberg has not shared his presentation, which usually makes me reluctant to share an idea in a roundup like this, but this idea has kept my skeptic&amp;#x27;s brain humming since he laid it out. If it piques your interest at all, the &amp;quot;Introducing Thinkscape&amp;quot; demo on &lt;a href=&quot;https://unanimous.ai/&quot;&gt;Unanimous.ai&lt;/a&gt;&amp;#x27;s website provides a good starting point for learning more.&amp;nbsp; &lt;/p&gt;&lt;p&gt;&lt;strong&gt;Talks&lt;/strong&gt;&lt;/p&gt;&lt;ul&gt;&lt;li&gt;&lt;a href=&quot;https://conferences.infotoday.com/documents/458/1615_Fitzgerald.pdf&quot;&gt;Orchestrating the Mundane: Deskilling AI for Consistency &amp;amp; Reliability&lt;/a&gt;, Andy Fitzgerald, Andy Fitzgerald Consulting&lt;/li&gt;&lt;li&gt;&lt;a href=&quot;https://conferences.infotoday.com/documents/458/1215_Moore.pdf&quot;&gt;Beyond Chat Bots: LLMs &amp;amp; ‘Human-in-the-Loop’ Taxonomy Development at EA Games&lt;/a&gt;, Shannon Moore &amp;amp; Max Gaibort, Electronic Arts&lt;/li&gt;&lt;li&gt;&lt;a href=&quot;https://conferences.infotoday.com/documents/458/1345_Lee(1).pptx&quot;&gt;Aligning AI Approaches for Taxonomy &amp;amp; Tagging (Part I)&lt;/a&gt;, Erik Lee, Factor Firm&lt;/li&gt;&lt;li&gt;&lt;a href=&quot;https://conferences.infotoday.com/documents/458/1345_Jenkins.pdf&quot;&gt;Aligning AI Approaches for Taxonomy &amp;amp; Tagging (Part II)&lt;/a&gt;, Michele Ann Jenkins, Dovecot Studio&lt;/li&gt;&lt;li&gt;Collective Superintelligence: Humans in the Loop, Louis Rosenberg, &lt;a href=&quot;https://unanimous.ai/&quot;&gt;Unanimous.ai&lt;/a&gt;&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;And that&amp;#x27;s it! ... for the shared talks I saw personally. Do have a look at &lt;a href=&quot;https://www.taxonomybootcamp.com/2024/Presentations.aspx&quot;&gt;TBC&amp;#x27;s Presentations page&lt;/a&gt; for a full list of shared talks—or, better yet, put the event on your calendar for next year: they&amp;#x27;ll be &lt;a href=&quot;https://www.taxonomybootcamp.com/&quot;&gt;back in DC on the 17th and 18th of 2025&lt;/a&gt;. &lt;/p&gt;&lt;p&gt;In the meantime, if you&amp;#x27;re curious about previous TBC topics, check out &lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/insights/taxonomy-boot-camp-2022-themes-takeaways/&quot;&gt;Taxonomy Boot Camp 2022 Themes &amp;amp; Takeaways here&lt;/a&gt;. &lt;/p&gt;</content>
  </entry>
  <entry>
    <title type="text">Deskilling Large Language Models</title>
    <link rel="alternate" type="text/html" href="https://preview.andyfitzgeraldconsulting.com/insights/deskilling-large-language-models/"/>
    <id>https://preview.andyfitzgeraldconsulting.com/insights/deskilling-large-language-models/</id>
    <published>2024-10-27T00:00:00Z</published>
    <updated>2024-10-27T00:00:00Z</updated>
    <summary type="text">“Deskilling” is a method for framing language models in predictable structures in order to achieve consistent outcomes for well-defined tasks. </summary>
    <category term="Method"/>
    <category term="Prototyping"/>
    <category term="AI Integration"/>
    <category term="Technology Integration"/>
    <category term="Python"/>
    <content type="html">&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/8f789db6f62f392bb1fa2b540a8eabe8c12c04ea-2400x1801.png?rect=0,0,2400,1350&amp;amp;w=1200&amp;amp;h=675&amp;amp;fit=crop&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;675&quot; alt=&quot;A graph showing a start node which leads to a routing agent node, then to one of four facet nodes. Each of these leads to a tool node, then to a response agent and an end node. &quot; /&gt;&lt;/figure&gt;&lt;p&gt;Modern AI products make a lot of promises around the &amp;quot;expertise&amp;quot; delivered by their models. Sometimes, though, another expert is not what I (or my clients) need. “Deskilling” replaces the &amp;quot;magic&amp;quot; of an LLM &amp;quot;figuring everything out&amp;quot; with structured, predictable steps and then uses language models as the glue between natural language and computational tasks.&lt;/p&gt;&lt;p&gt;Modern &amp;quot;AI&amp;quot; products make a lot of promises around the &amp;quot;expertise&amp;quot; delivered by their models. And despite one persistent and vexing Achilles heel (i.e. making things up), these tools are getting better with each release.&lt;/p&gt;&lt;p&gt;Sometimes, though, another expert is not what I (or my clients) need. More often, what I really need is a reasonably capable, agreeable, hard-working assistant. More of an &amp;quot;Igor&amp;quot; than a &amp;quot;Dr Frankenstein.&amp;quot; After all, I&amp;#x27;m usually the one who&amp;#x27;s been hired to be the expert. In any case, I&amp;#x27;m the one who will be held responsible for the quality of the work I deliver, so I have a very real interest in understanding how it is performed.&lt;/p&gt;&lt;p&gt;While it is possible to constrain a language model to be a &amp;quot;lab assistant&amp;quot; through prompting alone, &amp;quot;experts&amp;quot; don&amp;#x27;t easily fit into &amp;quot;assistant&amp;quot; boxes. Frontier language models are &lt;em&gt;created&lt;/em&gt; to generate unique output perceived as &amp;quot;creative.&amp;quot; To fight this is to fight with the tool from the start.&lt;/p&gt;&lt;h2 id=&quot;language-model-deskilling&quot;&gt;Language Model Deskilling&lt;/h2&gt;&lt;p&gt;What to do, then, when rather than the latest &amp;quot;AI Expert,&amp;quot; what you really need is a reliable, consistent assistant? I&amp;#x27;ve been exploring this question over the last couple of months and have arrived at a process I call &amp;quot;deskilling” language models. Deskilling replaces the &amp;quot;magic&amp;quot; of an LLM &amp;quot;figuring everything out&amp;quot; with structured, predictable steps and then uses language models as the glue between natural language and computational tasks. In the experiments I&amp;#x27;ve run, I&amp;#x27;ve found this to be an effective approach for producing accurate, consistent results using simple, predictable models.&lt;/p&gt;&lt;p&gt;In this article, I&amp;#x27;ll share an overview of one such exploration and will provide guidelines for how language models can be deskilled for practical purposes along the way. I’ll also provide a set of considerations for steps we might take as information professionals to use language models productively and responsibly in our work.&lt;/p&gt;&lt;h2 id=&quot;why-deskilling&quot;&gt;Why &amp;quot;Deskilling&amp;quot;?&lt;/h2&gt;&lt;p&gt;In economics, &lt;a href=&quot;https://en.wikipedia.org/wiki/Deskilling&quot;&gt;deskilling&lt;/a&gt; is the “process by which skilled labor within an industry or economy is eliminated by the introduction of technologies operated by semi- or unskilled workers.&amp;quot; In the Industrial Revolution, for example, the introduction of mechanized looms meant that textile manufacture could be performed by low-wage unskilled labor. This allowed industrialists to push artisan weavers out of the craft and pocket the profits.&lt;/p&gt;&lt;p&gt;Understandably, the artisan weavers were miffed. The ensuing riots over this callous shenanigan are where we get the term “&lt;a href=&quot;https://www.history.com/news/who-were-the-luddites&quot;&gt;Luddite&lt;/a&gt;.” Language models, however, don&amp;#x27;t have families to support or student loans to pay off. They also don&amp;#x27;t get bored or angry when you ask them to perform repetitive, tedious, low-level linguistic tasks. Furthermore, if you&amp;#x27;re a business trying to figure out where and how LLMs created, owned, and operated by &lt;em&gt;other companies&lt;/em&gt; fit into your business plan—especially when those companies have unclear and shifting commercial goals—reducing your reliance on the &amp;quot;skill&amp;quot; of a particular model can be a smart way to hedge against risks in what is clearly a very fast moving set of technologies and interests.&lt;/p&gt;&lt;p&gt;As with the deskilling of human labor, when deskilling language models, the complexity of a task must be accounted for in other technologies. One way to accomplish this is through the purposeful orchestration of task &lt;em&gt;composition&lt;/em&gt;, &lt;em&gt;granularity&lt;/em&gt;, and &lt;em&gt;visibility&lt;/em&gt;. These facets allow you to displace the problematic features of language models&amp;#x27; so-called &amp;quot;reasoning&amp;quot; capabilities by reducing the complexity and scope of the linguistic tasks performed and coordinating the sequence in which work and decisions are performed.&lt;/p&gt;&lt;p&gt;💼 Let’s unpack that with an example.&lt;/p&gt;&lt;h2 id=&quot;a-wikidata-olympic-games-agent&quot;&gt;A WikiData Olympic Games Agent&lt;/h2&gt;&lt;p&gt;Earlier this year, I worked through an experiment of connecting an LLM to Wikidata, the publicly available and collaboratively edited multilingual knowledge graph hosted by the Wikimedia Foundation. I wanted to work through a method of interacting with a real-world knowledge graph that&amp;#x27;s capable of logically deducing new facts from an existing data store. The goal was to be able to answer questions with logical inferences derived from Wikidata&amp;#x27;s ontology.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/be3c67767cea0aca5455cf8b4f5679f34b256910-2286x1766.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;927&quot; alt=&quot;Screenshot of a VS Code window showing chat questions and responses that conform to the expectations of the sample questions and answers. &quot; /&gt;&lt;figcaption&gt;A WikiData 2024 Olympic Games agent using LangGraph&amp;#x27;s prebuilt agent and GPT-4o mini. &lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;As a test case, I drafted a set of questions about the medalists of the 2024 Summer Olympic Games that would require multi-hop retrieval, logical inference, and the acknowledgment of missing data:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;Who were the youngest medalists at the 2024 Summer Olympics, and what did they win?&lt;/li&gt;&lt;li&gt;What countries were the youngest medalists at the 2024 Summer Olympics from?&lt;/li&gt;&lt;li&gt;Who was the youngest medalist from Japan in the 2024 Summer Olympic Games?&lt;/li&gt;&lt;li&gt;What event in the 2024 Summer Olympics did the youngest medalist from Spain win?&lt;/li&gt;&lt;li&gt;What medal in the 2024 Summer Olympics did the youngest medalist from Spain win?&lt;/li&gt;&lt;li&gt;Who was the oldest medalist at the 2024 Olympics from a country in Africa?&lt;/li&gt;&lt;li&gt;Who was the youngest fencing medalist at the 2024 Olympic Games?&lt;/li&gt;&lt;li&gt;Who was the oldest medalist in weightlifting at the 2024 Summer Olympics?&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;The correct responses to these questions are too recent to be in any language model&amp;#x27;s training data and are not explicitly asserted in the Wikidata corpus. My hypothesis was that a language model could manipulate the parameters of a modular query sent to Wikidata&amp;#x27;s SPARQL endpoint, which would, in turn, generate a focused set of facts that would ground the LLM&amp;#x27;s natural language response.&lt;/p&gt;&lt;h3 id=&quot;first-test-the-prebuilt-langgraph-agent&quot;&gt;First Test: The Prebuilt LangGraph Agent&lt;/h3&gt;&lt;p&gt;I began tests of my WikiData Knowledge Graph hypothesis with a &amp;quot;prebuilt&amp;quot; LangGraph agent, using GPT-4o mini as the underlying language model. LangGraph is a framework for connecting language models and tools in a directed acyclic graph (DAG), which means it affords an opportunity for structural decision points in the way models are connected. It felt like a good place to start.&lt;/p&gt;&lt;p&gt;📘 &lt;a href=&quot;https://github.com/andybywire/llm-lab/blob/main/conversational-wikidata-rag-agent.ipynb&quot;&gt;Conversational Wikidata RAG Agent Notebook&lt;/a&gt; (GitHub)&lt;/p&gt;&lt;p&gt;The Prebuilt Agent model works like this:&lt;/p&gt;&lt;ol&gt;&lt;li&gt;A user question is provided at the start node and delivered to the agent&lt;/li&gt;&lt;li&gt;The agent evaluates the question and makes a decision: answer the question, or consult a &amp;quot;tool.&amp;quot; In this case, the tool is a prebuilt modular SPARQL query with verbose descriptions of the available query parameters and what kinds of data it returns&lt;/li&gt;&lt;li&gt;If a tool response is chosen, the agent formulates and sends the required inputs (the query parameters) to the tool&lt;/li&gt;&lt;li&gt;The tool executes the query and returns the formatted endpoint response to the agent&lt;/li&gt;&lt;li&gt;The agent re-evaluates the initial user query in light of the tool response and can decide to formulate a response or re-query the tool&lt;/li&gt;&lt;li&gt;When a response is finally formulated, the agent calls the end node and delivers the response to the user.&lt;/li&gt;&lt;/ol&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/93b0b1f73587a1080758e6549a37f267f9327df0-2400x1351.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;676&quot; alt=&quot;A graph diagram with a start node pointing to an agent node, which points to a query node, which then points back to the agent node. There is a final arrow to an end node.&quot; /&gt;&lt;/figure&gt;&lt;p&gt;You may wonder why one wouldn&amp;#x27;t skip the tool step altogether and just let the agent formulate the SPARQL query. GPT-4o mini is certainly game to try. I quickly found, however, that even though the language model&amp;#x27;s queries were formally &amp;quot;correct,&amp;quot; they usually failed to produce any results (let alone useful ones) in the face of Wikidata&amp;#x27;s real-world complexity. They also never came close to producing a result that inferred new information.&lt;/p&gt;&lt;p&gt;Separating the SPARQL query from the language model and providing clearly defined modular parameters represents a first step of deskilling the model through the &lt;em&gt;composition&lt;/em&gt; of discrete tasks. LangGraph also provides &lt;em&gt;visibility &lt;/em&gt;into the inputs and outputs of each node in the graph, which is crucial to iterating the model purposefully.&lt;/p&gt;&lt;p&gt;When executed against the test questions, this model worked reasonably well. It was able to answer most questions accurately based on the returned Wikidata facts, and was able to accurately incorporate its own general &amp;quot;knowledge&amp;quot; of the world to answer questions indirectly contained in the dataset (this is the case the question about the &amp;quot;oldest medalist from Africa&amp;quot; is designed to test).&lt;/p&gt;&lt;p&gt;When inspecting the model&amp;#x27;s performance, however, I found these correct responses were often the result of multiple tool calls and GPT-4o mini&amp;#x27;s ability to deal with large context inputs, which helped it find answers amid a messy (and often unrelated) set of source facts. When I limited the number of times the model could re-invoke the tool, its accuracy rate dropped significantly—from almost 100% to being right only half of the time.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/ccda5c261a4c9d978c2d1013926bce950c8c9ef8-2400x1484.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;742&quot; alt=&quot;a bar chart showing that agent zero gave four correct answers, and four incorrect answers.&quot; /&gt;&lt;/figure&gt;&lt;h3 id=&quot;agent-zero&quot;&gt;Agent Zero&lt;/h3&gt;&lt;p&gt;To further explore the degree to which this structural configuration was dependent on the language model, I swapped out the hosted model, GPT-4o mini, with an agent that could run locally on my MacBook Pro: Llama 3.1-8b.&lt;/p&gt;&lt;p&gt;📘 &lt;a href=&quot;https://github.com/andybywire/llm-lab/blob/main/local-wikidata-agent-0.ipynb&quot;&gt;Agent Zero Notebook&lt;/a&gt; (GitHub)&lt;/p&gt;&lt;p&gt;As you might expect, the results were abysmal. To my surprise, it did respond correctly almost half of the time, but its incorrect responses were sophomorically verbose: it tended to just spit out whatever response it got from the tool and call it good.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/fa0c9b4826a717446ba428eeb2c0584382063078-2400x1484.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;742&quot; alt=&quot;a bar chart showing that agent zero got five questions wrong, and three right&quot; /&gt;&lt;/figure&gt;&lt;p&gt;In effect, Agent Zero represents a half-completed job of deskilling: I had swapped out the labor, but did nothing to improve the technology.&lt;/p&gt;&lt;p&gt;No profits to pocket for me.&lt;/p&gt;&lt;h3 id=&quot;second-test-agent-one&quot;&gt;Second Test: Agent One&lt;/h3&gt;&lt;p&gt;Given the high volume word salad Agent Zero favored for responses, I theorized that one key problem was the amount of information returned from the Wikidata SPARQL endpoint. Both the Prebuilt Agent and Agent Zero returned very large result sets. If I presented Llama 3.1 with a smaller set of facts, perhaps it would more consistently be able to process them.&lt;/p&gt;&lt;p&gt;📘 &lt;a href=&quot;https://github.com/andybywire/llm-lab/blob/main/local-wikidata-agent-1.ipynb&quot;&gt;Agent One Notebook&lt;/a&gt; (GitHub)&lt;/p&gt;&lt;p&gt;For Agent One, then, I broke the decisions of &lt;em&gt;what to ask&lt;/em&gt; and &lt;em&gt;how to ask it&lt;/em&gt; into two separate steps by creating a &amp;quot;routing agent&amp;quot; responsible for deciding what the question was about, and set of &amp;quot;facet agents&amp;quot; designed to formulate a specific subset of query parameters (based on their designated facet). Each facet agent calls the query tool, passing in only the parameters that concern it. The query result is subsequently passed to a &amp;quot;response agent&amp;quot; that evaluates the question in light of the facts provided and formulates a response for the user.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/8f789db6f62f392bb1fa2b540a8eabe8c12c04ea-2400x1801.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;901&quot; alt=&quot;A graph showing a start node which leads to a routing agent node, then to one of four facet nodes. Each of these leads to a tool node, then to a response agent and an end node. &quot; /&gt;&lt;/figure&gt;&lt;p&gt;This agent builds on the DAG I had established in the Prebuilt Agent and adds in a separation of concerns which, theoretically, creates a greater degree of &lt;em&gt;granularity&lt;/em&gt; for each agent. The prompts for each type of agent, and for each facet agent, define a smaller purview for each, ascribing a narrower range of action. The agents are then coordinated to eliminate the need for redundant tool node instances.&lt;/p&gt;&lt;p&gt;At first glance, Agent One’s performance on test questions seemed to be an improvement. The number of consistently &amp;quot;right&amp;quot; answers in the test set doubled compared to Agent Zero.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/ab36fd35b1e303423b954da743622c7377b910a8-2400x1484.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;742&quot; alt=&quot;a bar chart showing that agent one got six questions right and missed two.&quot; /&gt;&lt;/figure&gt;&lt;p&gt;The answers that were wrong, however, were wrong in suspiciously inconsistent ways. Sometimes the right data was returned, but not interpreted correctly. Sometimes different questions were wrong for different reasons across multiple tests under the same conditions.&lt;/p&gt;&lt;p&gt;LangGraph uses a shared &amp;quot;scratchpad&amp;quot; of data called “state” to communicate between nodes. This offers a degree of &lt;em&gt;visibility&lt;/em&gt; not possible with language models alone. By inspecting Agent One’s state, I was able to see exactly what messages, parameters, and prompts were passed between each node. What I discovered was that though Agent One returned correct answers most of the time, the Routing Agent was not very consistent at directing questions to the right facet agent, and the facet agents completely ignored the parameter constraints described in their system prompts.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/02a1fa1c4fe4b6c23311c592652e49d1b3336112-2400x1600.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;800&quot; alt=&quot;a LangSmith trace screen, showing that the event agent did not set the event parameter&quot; /&gt;&lt;figcaption&gt;An Agent One interaction trace, shown in the LangSmith inspection tool
&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;In the above image, for instance, we can see that the Routing Agent sent this question to the wrong facet agent: the &amp;quot;event&amp;quot; in question is what we need to know, not an available value for a parameter. We can also see that the Event Agent ignored its instruction to always return an &amp;quot;event&amp;quot; parameter.&lt;/p&gt;&lt;p&gt;Agent One ultimately got the answer right, but not in a way that would allow it to scale to answering more complex queries consistently. The &lt;em&gt;visibility&lt;/em&gt; of these interactions helped me troubleshoot the agent and recognize that this approach was still not sufficiently granular to behave predictably.&lt;/p&gt;&lt;h3 id=&quot;third-test-agent-two&quot;&gt;Third Test: Agent Two&lt;/h3&gt;&lt;p&gt;Agent One demonstrated that asking the LLM to choose which query parameters to set was still too complex of a task for Llama 3.1. In fact, allowing the configuration of multiple parameters was even problematic for GPT-4o mini: I suspect GPT-4o mini was only able to manage verbose Wikidata returns because it handled its context window better.&lt;/p&gt;&lt;p&gt;📘 &lt;a href=&quot;https://github.com/andybywire/llm-lab/blob/main/local-wikidata-agent-2.ipynb&quot;&gt;Agent Two Notebook&lt;/a&gt; (GitHub)&lt;/p&gt;&lt;p&gt;The structure of Agent Two simplifies these decisions by eliminating them: instead of facet agents that handle clusters of related parameters, Agent Two uses one agent for each parameter. Those agents&amp;#x27; only responsibility: determine the value for their assigned parameter.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/478b6a03dea778d0a43a4ea3059ae3b01196b355-2400x1350.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;675&quot; alt=&quot;A graph diagram showing a start node, then a sequence of four parameter nodes, leading to a response agent then an end agentthen a &quot; /&gt;&lt;/figure&gt;&lt;p&gt;This structure means that each parameter is evaluated for every question, and that each model only needs to return one of two things: an appropriate value based on the question, or &amp;quot;None&amp;quot; to indicate that no value is needed.&lt;/p&gt;&lt;p&gt;Each parameter is joined to the preceding parameter and the final query is delivered to a simple function (a &amp;quot;runnable lambda&amp;quot;) to retrieve the relevant Wikidata facts. These facts are then passed to a final response agent with strict instructions to answer the original question based only on the facts provided.&lt;/p&gt;&lt;p&gt;Since model-based decisions have been eliminated in this example, a simpler linear &amp;quot;chain&amp;quot; of agents replaces the DAG. Individual parameter agents are also considerably simpler in structure than their Facet Agent counterparts, which means the code to create them is more streamlined and simpler to iterate.&lt;/p&gt;&lt;p&gt;In terms of final response accuracy, Agent Two generated the same number of correct responses as Agent One:&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/659386a6725979f889506fea5a92a762d3eb9434-2400x1484.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;742&quot; alt=&quot;A bar graph showing that agent two got six questions right and two questions wrong.&quot; /&gt;&lt;/figure&gt;&lt;p&gt;Agent Two still consistently misses two questions. There is a key difference, however: Agent Two always misses the same two questions, and it misses them not because it has returned the wrong facts (or too many facts) from Wikidata, but rather because the final response model consistently misinterprets facts about Spanish athletes&amp;#x27; ages.&lt;/p&gt;&lt;p&gt;By examining the model trace in LangSmith, we can see that the query parameters created by Agent Two are accurate for the question asked:&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/966d050d6b78a3e9a3fe5785488c675b75c2bb93-2400x1600.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;800&quot; alt=&quot;A LangSmith trace showing that agent two set the search parameters coorectly.&quot; /&gt;&lt;figcaption&gt;An Agent Two interaction trace, shown in the LangSmith inspection tool&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;It’s when Llama 3.1 is asked to interpret that data, however, that things go sideways:&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/8f265cfc378397e746a5e6272efb25a79be6c3d1-2400x1134.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;567&quot; alt=&quot;What event in the 2024 Summer Olympics did the youngest medalist from Spain win?AI Response: Jordan Diaz won a gold medal in athletics at the 2024 Summer Olympics, men&amp;#x27;s triple jump. He is 23 years old, which is younger than Carlos Alacaraz who is 21 and Sara Sorribes Tormo who is 27. Therefore, Jordan Diaz was the youngest medalist from Spain. Correct Response:Men&amp;#x27;s tennis singles, Carlos Alacaraz, 21&quot; /&gt;&lt;/figure&gt;&lt;p&gt;This is still, obviously, a problem that needs to be addressed. But it is a &lt;em&gt;different&lt;/em&gt; problem than the one I set out to address in this experiment: how to dynamically generate a focused set of facts to ground an LLM&amp;#x27;s natural language response. That problem was resolved by &lt;em&gt;composing&lt;/em&gt; tasks at the appropriate degree of &lt;em&gt;granularity&lt;/em&gt; and iterating candidate structures by adjusting &lt;em&gt;visible&lt;/em&gt; interactions and touchpoints to arrive at an effective solution.&lt;/p&gt;&lt;h2 id=&quot;deskilling-takeaways&quot;&gt;Deskilling Takeaways&lt;/h2&gt;&lt;p&gt;There is &lt;em&gt;a lot&lt;/em&gt; of content out there right now about language model tools, technologies, and patterns. I haven&amp;#x27;t gone into the specifics of prompt composition, LangChain/LangGraph/LangSmith, or running models locally because there are already scores of excellent tutorials out there to get you started.&lt;/p&gt;&lt;p&gt;In addition to the technical implementation of model composition, however, there is also a set of problem solving and design considerations that need to be taken into account when using language models for practical work. &amp;quot;Deskilling&amp;quot; is one way to think through those considerations, and the manipulation and iteration of task &lt;em&gt;composition&lt;/em&gt;, &lt;em&gt;granularity&lt;/em&gt;, and &lt;em&gt;visibility&lt;/em&gt; offer three facets by which it might be accomplished.&lt;/p&gt;&lt;p&gt;As the examples above demonstrate, deskilling is a continuum. Some tasks can be abstracted to structural tools (and a less &amp;quot;capable&amp;quot; LLM); others will require a more advanced model or human supervision—or both. In either case, the work of designing effectively orchestrated models is not engineering work alone: we must also understand and be able to articulate the goals, outputs, interactions, and points of failure of a model. These insights help us align the messy, imprecise realm of natural language with the deterministic realm of machine-readable facts and executable functions.&lt;/p&gt;&lt;p&gt;Deskilling also offers a path to understanding when an LLM is simply the wrong solution. In the final example above, where the Response Agent receives the right facts but fails to interpret them correctly, we could consider using a more advanced model to remedy the problem. Alternatively, we could also just deliver the returned facts as a response. Is there really more value to having a language model rephrase a concise set of clearly worded statements? The answer will depend on the use case, but it’s worth considering that using a language model here just because we&amp;#x27;ve used them already may deliver a poorer experience at greater cost.&lt;/p&gt;&lt;p&gt;The rate at which language models and language model tooling have evolved over the last couple of years is truly stunning. I see every reason to believe they will continue to afford new ways to create useful, usable ways to find, understand, create, and share knowledge. While guidance for how to use language models judiciously and responsibly has not emerged with the same velocity as the tools themselves, my hope is that &amp;quot;deskilling&amp;quot; offers a point of view that helps you employ language models—or not—in a conscientious, purposeful way.&lt;/p&gt;</content>
  </entry>
  <entry>
    <title type="text">Taxonomy Boot Camp 2022 Themes &amp; Takeaways</title>
    <link rel="alternate" type="text/html" href="https://preview.andyfitzgeraldconsulting.com/insights/taxonomy-boot-camp-2022-themes-takeaways/"/>
    <id>https://preview.andyfitzgeraldconsulting.com/insights/taxonomy-boot-camp-2022-themes-takeaways/</id>
    <published>2022-11-17T00:00:00Z</published>
    <updated>2022-11-17T00:00:00Z</updated>
    <summary type="text">Summary of the top themes and insights from the 2022 Taxonomy Boot Camp conference in Washington DC</summary>
    <category term="Conference Themes"/>
    <category term="Knowledge Graphs"/>
    <category term="Collaborative Design"/>
    <category term="Taxonomy"/>
    <category term="Structured Content"/>
    <content type="html">&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/14e13481e71f4ba35b3bd3999430ea0687848bff-4000x2000.png?rect=226,0,3556,2000&amp;amp;w=1200&amp;amp;h=675&amp;amp;fit=crop&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;675&quot; alt=&quot;Cover slides from six talks presented at Taxonomy Boot Camp 2022&quot; /&gt;&lt;/figure&gt;&lt;p&gt;Last week I had the pleasure and privilege of attending the 18th annual Taxonomy Boot Camp in Washington DC. This year’s conference carried on its strong tradition of ideas, talks, and workshops for neophytes and experts alike, and, as always, provided much food for thought. Here’s a roundup of the themes and topics I saw recurring across talks, plus (as always) a bit of commentary on where I see them fitting into the bigger picture of designing information spaces that are easy to understand and pleasant to use.&lt;/p&gt;&lt;p&gt;Last week I had the pleasure of attending and presenting at &lt;a href=&quot;https://www.taxonomybootcamp.com/2022/Default.aspx&quot;&gt;Taxonomy Boot Camp&lt;/a&gt; in Washington DC. This was the boot camp’s 18th year, and the third time I’ve attended since 2016. This conference is historically framed as a life ring for those thrown into the deep waters of taxonomy design, implementation, and management, but in the few years that I’ve been going, I’ve seen it also evolve into a forum for working professionals to share case studies, best practices, and innovations in the field.&lt;/p&gt;&lt;p&gt;This year’s boot camp carried on that tradition of ideas, talks, and workshops for neophytes and experts alike. Here is a roundup of the top themes and insights I took away from the sessions I attended. Most speakers have shared their slides and Taxonomy Boot Camp (TBC) has graciously made these available for anyone to download, so I’ve included links to decks where available. You can &lt;a href=&quot;https://www.taxonomybootcamp.com/2022/Presentations.aspx&quot;&gt;access the whole list here&lt;/a&gt;.&lt;/p&gt;&lt;h2 id=&quot;top-themes-takeaways&quot;&gt;Top Themes &amp;amp; Takeaways&lt;/h2&gt;&lt;h3 id=&quot;1-taxonomy-is-about-people&quot;&gt;1. Taxonomy is about &lt;em&gt;people&lt;/em&gt;&lt;/h3&gt;&lt;p&gt;In my experience, prior year TBC talks often focused on more technical aspects of getting taxonomy projects off the ground and implemented. Standards, automation, and systems integration were common themes. There were certainly some of these topics this year, but the thread I saw running through most talks was how taxonomies affect and are affected by the people who use and create them.&lt;/p&gt;&lt;p&gt;This theme was framed beautifully by the opening keynote speaker, David Dylan Thomas, who opened the conference with “&lt;a href=&quot;https://conferences.infotoday.com/documents/411/0910_Thomas.pptx&quot;&gt;Design for Cognitive Bias: Using Mental Shortcuts for Good Instead of Evil&lt;/a&gt;.” Thomas is an active, engaged advocate for understanding the power of human bias in design and his talk emphasized the impact of the “cognitive shortcuts”  we use to navigate the &lt;a href=&quot;https://www.cnn.com/2022/04/21/health/decision-fatigue-solutions-wellness/index.html#:~:text=Whether%20you&amp;#x27;re%20making%20breakfast,Leicester%20in%20the%20United%20Kingdom.&quot;&gt;tens of thousands of decisions&lt;/a&gt; we make each day. As taxonomy is frequently used to constrain what can and cannot be said within a system, this early focus on biases—especially hidden biases—opened the conference with an important reminder of the power and responsibility implicit in taxonomy work.&lt;/p&gt;&lt;p&gt;&lt;strong&gt;Talks&lt;/strong&gt;&lt;/p&gt;&lt;ul&gt;&lt;li&gt;&lt;a href=&quot;https://conferences.infotoday.com/documents/411/0910_Thomas.pptx&quot;&gt;Design for Cognitive Bias: Using Mental Shortcuts for Good Instead of Evil&lt;/a&gt;, David Dylan Thomas, David Dylan Thomas, LLC.&lt;/li&gt;&lt;/ul&gt;&lt;h3 id=&quot;2-hierarchies-and-graphs-are-complementary&quot;&gt;2. Hierarchies and Graphs are Complementary&lt;/h3&gt;&lt;p&gt;A respectable proportion of this year’s talks focused or at least touched on the role of taxonomy in knowledge graphs and ontologies. Likewise, more than a few audience questions demonstrated that many folks are still trying to untangle and define the differences between ontologies and taxonomies, knowledge graphs, and what all of this means for existing data management strategies.&lt;/p&gt;&lt;p&gt;Ahren Lehnert of &lt;a href=&quot;https://www.synaptica.com/&quot;&gt;Synaptica&lt;/a&gt;, a taxonomy and ontology software vendor, gave a pithy, practical gloss on how taxonomies and ontologies relate (parentheticals mine):&lt;/p&gt;&lt;ul&gt;&lt;li&gt;Hierarchies (which are often expressed as taxonomies) are for classification&lt;/li&gt;&lt;li&gt;Graphs (which are often expressed as ontologies) are for exploration&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;From Lehnert’s perspective, taxonomies encode hierarchical relationships and impose a singular, often immutable viewpoint. Ontologies decentralize hierarchical relationships and provide alternate (sometimes surprising) views on the data hierarchical taxonomies encode. According to Lehnert, these two concepts combined create a “concept cartography”:  a taxonomy is a “map of a concept”; an ontology operates as “the legend of the map.”&lt;/p&gt;&lt;p&gt;One ongoing challenge in helping folks make sense of knowledge graphs (and ontologies and the role taxonomies play in both) is the fact that the way these elements come together can vary wildly between organizations, applications, and levels of maturity. For example, Jenni Doughty and Tatiana Cakici from &lt;a href=&quot;https://enterprise-knowledge.com/&quot;&gt;Enterprise Knowledge&lt;/a&gt; presented a knowledge graph method and case study that moved through a linear vision, analysis, design, validation, implementation process, while Donna Popkey from the Harvard Business School presented a knowledge graph case study that was built around connecting silos with a hub and spoke model—without, as she put it, “creating a big hairball.”&lt;/p&gt;&lt;p&gt;A team from Etsy, on the other hand, presented a case study on incorporating semantic data (their ontology) into a traditional taxonomic hierarchy. Whether or not one chooses to classify Etsy’s work as “a knowledge graph,” they’re doing the hard work of incorporating nuanced semantics into the way they manage and understand their incredibly diverse body of content. Different contexts and needs in each case called for quite different solutions.&lt;/p&gt;&lt;p&gt;&lt;strong&gt;Talks&lt;/strong&gt;&lt;/p&gt;&lt;ul&gt;&lt;li&gt;&lt;a href=&quot;https://conferences.infotoday.com/documents/411/1430_Lehnert.pdf&quot;&gt;Hierarchies, Meet Graphs&lt;/a&gt;, Ahren E Lehnert, Synaptica&lt;/li&gt;&lt;li&gt;&lt;a href=&quot;https://conferences.infotoday.com/documents/411/1515_Cakici.pdf&quot;&gt;Climbing the Ontology Mountain to Achieve a Successful Knowledge Graph&lt;/a&gt;, Jenni Doughty and Tatiana Cakici, Enterprise Knowledge&lt;/li&gt;&lt;li&gt;&lt;a href=&quot;https://conferences.infotoday.com/documents/411/1345_Hedden.pdf&quot;&gt;Harvard Business School Knowledge Hub and Spoke Model&lt;/a&gt;, Donna Popkey, Harvard Business School&lt;/li&gt;&lt;li&gt;&lt;a href=&quot;https://conferences.infotoday.com/documents/411/1045_Shimpeno.pdf&quot;&gt;When Taxonomy Met Ontology at Etsy&lt;/a&gt;, Marc Shimpeno, Susannah Woodbury, Jenn Borrell, and Ren Pope, Etsy&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;👉 For more themes on what’s going on in the world of knowledge graphs, check out my &lt;a href=&quot;https://www.linkedin.com/pulse/knowledge-graph-conference-2022-themes-top-takeaways-fitzgerald-phd/&quot;&gt;Knowledge Graph Conference 2022 Themes &amp;amp; Top Takeaways&lt;/a&gt; post.&lt;/p&gt;&lt;h3 id=&quot;3-taxonomy-work-is-teamwork&quot;&gt;3. Taxonomy Work is Teamwork&lt;/h3&gt;&lt;p&gt;This theme was certainly not new this year, but it does seem to be taking on increased significance. While in the past thesauri and taxonomies in the library sciences vein were primarily focused on indexing and retrieval, today taxonomy work (in which I include thesauri and ontologies) is more and more the connective tissue between information systems, organizations, industries, and entire theories of knowing and knowledge.&lt;/p&gt;&lt;p&gt;This is definitely a team sport.&lt;/p&gt;&lt;p&gt;And the players aren’t just taxonomists. In her talk on “shoestring taxonomies,” Emily Winks of WeWork highlighted the importance of “gathering friends” in the development of taxonomies: brand copywriters, content strategists, data, ML, and software engineers, librarians, UX researchers, and self-professed grammar sticklers are all among the folks she suggests. Winks also highlighted the importance of teamwork in making sure that the taxonomies one creates have the greatest impact. In her WeWork case study, the different taxonomies she designed found homes in WeWork’s Skills &amp;amp; Interests graph database, its Amenities API, and its Spaces Digital Asset Management System.&lt;/p&gt;&lt;p&gt;Crucially, taxonomy creation and placement isn’t the end of the work. Far from it. Taxonomy expert Bob Kasenchak of &lt;a href=&quot;https://factorfirm.com/&quot;&gt;Factor Firm&lt;/a&gt; noted in the “Stump the Taxonomist” panel session that “a taxonomy is a living document. If you don’t keep updating it, it becomes ossified, a snapshot of the moment in time at which it was built.” &lt;/p&gt;&lt;p&gt;Taxonomist Valerie Miller, who presented a rich and detailed case study of work she did at Politico, likewise shared an anecdote on the importance of keeping humans in the loop. In a news article in which one politician goaded another to show up to an upcoming event in a chicken suit, Politico’s auto-tagging system included the article in a “chicken-as-food” category. Had there not been a team to check those recommendations, that “related content” result would have been embarrassingly awkward. (Though likely not as embarrassing as &lt;a href=&quot;https://www.bbc.com/news/world-europe-63499057&quot;&gt;the recent incident KFC very publicly failed to avoid&lt;/a&gt; in promoting crispy chicken for the observance of Kristallnacht)&lt;/p&gt;&lt;p&gt;Taxonomy consultant Helen Lippell shared another common peril of not engaging broadly and thoroughly with stakeholders and subject matter experts. When asked during the “Stump the Taxonomist” panel session how to avoid the &amp;quot;miscellaneous&amp;quot; category, she responded “If you have a lot of ‘miscellaneous,’ your domain model is probably wrong.” &lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/insights/domain-modeling/&quot;&gt;Getting the domain model right&lt;/a&gt; is another crucial task for which iteration and collaboration are essential.&lt;/p&gt;&lt;p&gt;&lt;strong&gt;Talks&lt;/strong&gt;&lt;/p&gt;&lt;ul&gt;&lt;li&gt;&lt;a href=&quot;https://conferences.infotoday.com/documents/411/1200_Winks.pptx&quot;&gt;Shoestring Taxonomy: Limited Resources but Limitless Enthusiasm&lt;/a&gt;, Emily Winks, WeWork&lt;/li&gt;&lt;li&gt;&lt;a href=&quot;https://conferences.infotoday.com/documents/411/1130_Miller.pptx&quot;&gt;Tags to Topics: Politico’s Automated Classification System&lt;/a&gt;, Valerie Miller&lt;/li&gt;&lt;/ul&gt;&lt;h3 id=&quot;andys-2-taxonomy-and-the-headless-cms&quot;&gt;Andy’s 2¢: Taxonomy and the Headless CMS&lt;/h3&gt;&lt;p&gt;My own talk, “&lt;a href=&quot;https://conferences.infotoday.com/documents/411/1300_Fitzgerald.pdf&quot;&gt;Taxonomy and the Headless CMS&lt;/a&gt;,” fits into the “Taxonomy is about people” and “Taxonomy work is teamwork” themes a bit differently. By removing the page display focused “head” from content management systems, headless CMSes also remove an important set of heuristics that content creators use to structure information. When those of us who design content creation environments don’t fill that empty space with a set of tools consistent with the benefits of headless content creation, content producers and client organizations tend to fill it with what they know: page builders—which, ironically, work &lt;em&gt;against&lt;/em&gt; the very decoupling for which headless CMSes exist.&lt;/p&gt;&lt;p&gt;To illustrate where taxonomists can help to remedy this self-defeating workaround, I provided a set of examples from my recent client work where taxonomy practices were used to displace the language of layout based on pages and help producers create well formed structured content better suited for reuse, repurposing, and customization. This “structured content design” theme  is one that I’ve yet to see gain broader traction in taxonomy, IA, and knowledge graph conferences, but I’m convinced it’s essential to making content last longer and work harder, so I’m happy to spread the word from any soapbox I can find. If your curiosity is piqued, please do have a look at my collection of &lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/insights/?topic=structured-content&quot;&gt;articles on structured content design&lt;/a&gt; and my &lt;a href=&quot;https://www.linkedin.com/pulse/structured-content-2022-themes-top-takeaways-andy-fitzgerald-phd/&quot;&gt;2022 Structured Content Conference Themes &amp;amp; Top Takeaways post&lt;/a&gt;—and please do get in touch if you’d like to see a talk on structured content design at a future conference or event you’re organizing.&lt;/p&gt;&lt;p&gt;&lt;br/&gt;&lt;/p&gt;</content>
  </entry>
  <entry>
    <title type="text">Structured Content and the Headless CMS</title>
    <link rel="alternate" type="text/html" href="https://preview.andyfitzgeraldconsulting.com/insights/structured-content-headless-cms/"/>
    <id>https://preview.andyfitzgeraldconsulting.com/insights/structured-content-headless-cms/</id>
    <published>2022-07-19T00:00:00Z</published>
    <updated>2022-07-19T00:00:00Z</updated>
    <summary type="text">Structured content treats information as a set of ideas, concepts, and facts to communicate. </summary>
    <category term="Perspective"/>
    <category term="Structured Content"/>
    <category term="Interoperability"/>
    <category term="Content Modeling"/>
    <content type="html">&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/0ef60d9364767ffe5fbfe273d5f3b1c0506f17b3-1280x651.png?rect=62,0,1157,651&amp;amp;w=1157&amp;amp;h=651&amp;amp;fit=crop&amp;amp;auto=format&quot; width=&quot;1157&quot; height=&quot;651&quot; alt=&quot;A Garmin smart-watch, sitting on a wooden bench.&quot; /&gt;&lt;/figure&gt;&lt;p&gt;Are you still trying to wrap your head around what structured content is, how to use it, and what the benefit is to the folks who use your content? One way to think of it is that structured content treats information as a set of ideas, concepts, and facts to communicate, each described in a way that conveys its meaning in a machine readable way. Here&amp;#x27;s a brief illustration to demonstrate what that looks like.&lt;/p&gt;&lt;p&gt;I tend to get questions about headless CMSes:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;What &lt;em&gt;is&lt;/em&gt; a headless CMS? &lt;/li&gt;&lt;li&gt;How does a headless CMS work?&lt;/li&gt;&lt;li&gt;Should I get one?&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;There’s a lot of buzz around “going headless” these days. And these are valid questions that deserve to be answered. But they’re also usually the &lt;em&gt;wrong&lt;/em&gt; questions to start with. As structured content trailblazer (and Director of Content Strategy Relations for a headless CMS provider) &lt;a href=&quot;https://www.linkedin.com/in/carriehane/&quot;&gt;Carrie Hane&lt;/a&gt; noted at the &lt;a href=&quot;https://structuredcontent.live/program/structured-content-2022-keynote&quot;&gt;Structured Content&lt;/a&gt; conference in May: “A headless CMS won’t solve your content problem.” &lt;/p&gt;&lt;p&gt;In some cases, it could actually make it worse.&lt;/p&gt;&lt;p&gt;For most organizations, the most important thing a headless CMS will help you do is to create well-structured content. Carrie defines structured content as “content that is divided into the smallest reasonable pieces and explicitly organized and classified in order to be understood and used by computers and humans.” I love this definition, but it doesn’t quite paint a picture of what structured content accomplishes. Here&amp;#x27;s an example to help paint that picture.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/f97fd5a95322dcf9da3415e713bcbfd9713078d4-11628x5116.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;528&quot; alt=&quot;Garmin Forerunner smart watch, with the Run menu displayed on-screen.&quot; /&gt;&lt;/figure&gt;&lt;p&gt;Say you’re a user of a GPS running watch, like this Garmin Forerunner. It’s a pretty intuitive gadget (for a smartwatch), but sometimes you just need the manual. Fortunately, there is a “help” section in the accompanying Garmin iPhone app. Unfortunately, to get to any actual instructions, the app pushes you out to Garmin’s mobile web site.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/5d31e3e0612062a338caaf866d9191508b46bbfb-11628x8988.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;928&quot; alt=&quot;Help screen in the Garmin Forerunner app, and help screen on Garmin&amp;#x27;s mobile website.&quot; /&gt;&lt;/figure&gt;&lt;p&gt;This isn’t a terrible experience—Garmin kindly lands me on the help page for my watch—but I’d really rather stay in the app. The help site necessarily includes information and navigation I don’t need or want, and instructions and steps for other devices I’ll never use. It also strikes me as not designed as a mobile first experience.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/ab09fed256cf6440fc9734cf048b3de050108e31-11628x8988.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;928&quot; alt=&quot;Two screens from the Garmin mobile website help section, showing instructions for setting notifications on the Garmin Forerunner. &quot; /&gt;&lt;/figure&gt;&lt;p&gt;I don’t work with Garmin, so I won’t presume to know what their design constraints or resources are, but one hypothesis for why they don’t have this help content in context in the app is that it is being created explicitly &lt;em&gt;for&lt;/em&gt; the website. Recreating those web pages in the app may mean either rekeying the content (and then trying to keep it up to date), or plopping it into the app as a WebView, which often ends up being worse than just pushing someone to the website proper. The problem is (likely) that help content has been authored not as &lt;em&gt;a set of ideas to communicate&lt;/em&gt;, but rather as &lt;em&gt;pages&lt;/em&gt;—in this case, pages for a desktop website.&lt;/p&gt;&lt;p&gt;This is where structured content can help. In a structured content solution, help content is broken into small, meaningful chunks, each of which are described in a way that communicates that meaning. The smallest “meaningful chunk” of the notifications instructions above would likely include the Apple and Android instructions—each as a chunk and each described in a machine readable way as specific to those platforms—and an introductory paragraph that includes only the first sentence if your device is known, and adds the second sentence if not—say, if you’re visiting from a web page.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/26925d98095ed03a69088233c477b32abb15cf1a-11628x8988.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;928&quot; alt=&quot;Garmin help screen annotated to show possible structured content elements. &quot; /&gt;&lt;/figure&gt;&lt;p&gt;When content is described in this way, it becomes possible to instruct the native app to show only the content relevant to the device on which it’s running, and for the web site to choose to show both sets of steps and the additional context about operating systems. If that content is authored and managed in a headless CMS, both website and native application can draw on the same source (the headless CMS’s content API) for their content. The headless approach means each device can rely on a single source of truth, and display only the content it needs in the way that best suits its particular context and platform.&lt;/p&gt;&lt;p&gt;And here, finally, is why a headless CMS alone isn’t the solution to the “built for pages” content problem: if your content is &lt;em&gt;not&lt;/em&gt; structured meaningfully, and is &lt;em&gt;not&lt;/em&gt; described in a way that communicates that meaning in a machine readable way, you stand a good chance of ending up with the same problem you started with: content structured not as a set of ideas to communicate, but as a collection of pages. &lt;/p&gt;&lt;p&gt;This is a simple illustration, but also a real world context—one which, I’m not going to lie, is relevant to more than a couple devices in my house alone. It also shows what&amp;#x27;s possible when you make the shift from thinking about content as &lt;em&gt;pages&lt;/em&gt; to thinking about content as a set of &lt;em&gt;ideas, concepts, and facts to communicate&lt;/em&gt;, each described in a way that conveys its meaning in a machine readable way. Cross-channel publishing, as shown in this example, isn’t where the benefits of this approach end: we’re only just beginning to understand the potential structured content holds for personalization, localization, SEO, voice and chatbot design, and knowledge graph and semantic web integration.&lt;/p&gt;&lt;p&gt;As for web “pages,” they’ve been a good metaphor to help us get our heads around the mind-blowingly surreal fact that we now have so much knowledge instantly available at our fingertips. But it’s time to move on. If you create content that will be consumed online, embracing structured content is a great way to start.&lt;/p&gt;</content>
  </entry>
  <entry>
    <title type="text">Domain Modeling for Structured Content</title>
    <link rel="alternate" type="text/html" href="https://preview.andyfitzgeraldconsulting.com/insights/domain-modeling/"/>
    <id>https://preview.andyfitzgeraldconsulting.com/insights/domain-modeling/</id>
    <published>2022-01-27T00:00:00Z</published>
    <updated>2022-01-27T00:00:00Z</updated>
    <summary type="text">Learn to define the information structures and meaning that help structured content reach further and last longer.</summary>
    <category term="Method"/>
    <category term="Structured Content"/>
    <category term="Mental Models"/>
    <category term="Knowledge Graphs"/>
    <category term="Content Modeling"/>
    <content type="html">&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/898fa4c8b9e1c904da0e7442add6872ccd8fbe5c-1300x500.jpg?rect=117,0,888,500&amp;amp;w=888&amp;amp;h=500&amp;amp;fit=crop&amp;amp;auto=format&quot; width=&quot;888&quot; height=&quot;500&quot; alt=&quot;A stylized domain model of the UX Methods subject domain&quot; /&gt;&lt;/figure&gt;&lt;p&gt;Domain modeling helps organizations discover the information structures and meaning that allow structured content to reach further and last longer. By uncovering the assumptions and tacit rules that plague your content ecosystem, domain modeling can help you facilitate the shared vision necessary to create resilient, scalable systems for communication across channels.&lt;/p&gt;&lt;p&gt;Domain modeling helps organizations discover the information structures and meaning that allow &lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/insights/structured-content-design-22/&quot;&gt;structured content&lt;/a&gt; to reach further and last longer. By uncovering the assumptions and tacit rules that plague your content ecosystem, domain modeling can help you facilitate the shared vision necessary to create resilient, scalable systems for communication across channels.&lt;/p&gt;&lt;p&gt;In the context of content design, an organization’s “domain” is the information space in which that organization operates. It encompasses the organization’s sphere of activity, influence, and interest relative to business and user goals. The domain is the larger context in which all these elements are situated.&lt;/p&gt;&lt;p&gt;For the content and functionality that digital products like apps and websites deliver, the domain includes the set of circumstances, background knowledge, and purpose that drives users to seek out and use services and content. For example:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;&lt;strong&gt;Médecins Sans Frontières&lt;/strong&gt; (Doctors Without Borders) operate within the domain of “humanitarian aid”&lt;/li&gt;&lt;li&gt;&lt;strong&gt;Netflix&lt;/strong&gt; operates within the “streaming media” domain&lt;/li&gt;&lt;li&gt;&lt;strong&gt;Toyota&lt;/strong&gt; is situated in the domain of “automobile manufacturing”&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;A domain &lt;em&gt;model&lt;/em&gt; is a formal representation of the concepts that are important to how an organization communicates and operates in a given domain. The modeling process identifies and defines key concepts, and describes the consistent, predictable relationships between concepts in the domain.&lt;/p&gt;&lt;h2 id=&quot;how-to-model-a-domain&quot;&gt;How to Model a Domain&lt;/h2&gt;&lt;p&gt;The primary goals of domain modeling are to identify the key concepts in a particular domain, then clearly articulate how those concepts relate in a consistent and predictable way. The resulting insight provides a foundation for a holistic structured content design process, and brings with it the myriad benefits that come with a clear, shared understanding of the meaning of concepts, labels, and relationships.&lt;/p&gt;&lt;p&gt;The steps I use for domain modeling to support structured content design are:&lt;/p&gt;&lt;ol&gt;&lt;li&gt;Research the domain&lt;/li&gt;&lt;li&gt;Identify and define domain concepts&lt;/li&gt;&lt;li&gt;Review and refine concepts and definitions&lt;/li&gt;&lt;li&gt;Model domain relationships&lt;/li&gt;&lt;li&gt;Review and refine the relationship model&lt;/li&gt;&lt;/ol&gt;&lt;h3 id=&quot;1-research-the-domain&quot;&gt;1. Research the Domain&lt;/h3&gt;&lt;p&gt;Researching the domain involves two interlinked steps: identifying what your domain &lt;em&gt;is&lt;/em&gt;, and then identifying the concepts that characterize that domain and your organization’s role in it. Both of these steps draw on common qualitative research techniques, including:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;Stakeholder and subject matter expert (SME) interviews&lt;/li&gt;&lt;li&gt;User interviews&lt;/li&gt;&lt;li&gt;Content indexing &amp;amp; auditing&lt;/li&gt;&lt;li&gt;Competitive analysis&lt;/li&gt;&lt;li&gt;Contextual inquiry&lt;/li&gt;&lt;li&gt;Primary research review (including journey maps and task flows)&lt;/li&gt;&lt;li&gt;Secondary industry research review&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;Two questions that can help you identify and describe your domain are:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;What makes this domain distinct from similar subject domains?&lt;/li&gt;&lt;li&gt;What are the boundaries of this domain from my user’s point of view?&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;For example, a recent client in the education space initially assumed their domain was “education,” or “educational materials.” As we dug into their content, business model, and user needs, however, we discovered that a better definition of their domain was “primary education and learning.” This framing helped us more effectively collect and identify concepts and focus our initial research in the right direction.&lt;/p&gt;&lt;p&gt;Once you have an initial sense of what your domain is, list the potential concepts that characterize the domain and your organization’s (and their users’) role in it. For this exercise, the best domain concepts are ones that:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;Represent a specific type of thing (as opposed to a specific instance of that type)&lt;/li&gt;&lt;li&gt;Represent concepts that are central to, or have a particular purpose in your domain (as opposed to concepts that are likely to appear in any domain)&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;For the client in the “primary education and learning” domain discussed above, “instructional modality” was a good concept. The particular types of modality, “game,” “worksheet,” “song,” etc, were too specific. Likewise, “instructional resource” was included because in this client’s domain, that concept has a very specific meaning and importance, both to users and to the business.&lt;/p&gt;&lt;p&gt;As you collect candidate concepts, list them in a spreadsheet. Use the principles above to weed out the clear rejects, but don’t be too picky at this point: if you’re in doubt, include the concept. Not every one of these “candidate” concepts will figure into the domain model moving forward, but it is important to list them all to ensure you’re not leaving something important out.&lt;/p&gt;&lt;p&gt;To respect the confidentiality of my clients, I am only providing high level (or blurred) descriptions of client project work here. In order to provide concrete, readable versions of workflow artifacts and deliverables, here is an example from a recent personal project on which I used this same process, &lt;a href=&quot;https://uxmethods.org/&quot;&gt;UX Methods&lt;/a&gt;:&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/7fbb3e24a4ca62333bc368220415c78857d02822-1300x660.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;609&quot; alt=&quot;Screenshot of a spreadsheet showing a list of concepts in the User Experience Design Practices and Techniques domain, including Method, Discipline, Goal, Outcome, Step, etc.&quot; /&gt;&lt;figcaption&gt;Initial concept list for the User Experience Design Practices and Techniques domain identified for UX Methods.&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;👉 &lt;em&gt;I’ll return to this example as we go to give you a running account of how each step builds on what came before, and how the output can be structured for use in subsequent steps.&lt;/em&gt;&lt;/p&gt;&lt;h3 id=&quot;2-identify-and-define-domain-concepts&quot;&gt;2. Identify and Define Domain Concepts&lt;/h3&gt;&lt;p&gt;For client projects, I typically end up with 50 - 100 candidate concepts for a given subject domain. Once you have a good collection of candidates, narrow the list down to a handful of central concepts on which you’ll focus. Lean on your research and consult with stakeholders. Which are the concepts that are central to why and how your organization and users engage in the domain? Which concepts fundamentally distinguish this domain from other domains? If you end up with more than 20 or so “core” concepts, consider whether you may really dealing with two connected but distinct domains. (And if so, split them up!)&lt;/p&gt;&lt;p&gt;Next, define your core concepts based on your research. You should be able to define your concepts in 1 - 2 sentences. If you need to do more explaining than that, consider breaking the concept down into separate ideas. It is also helpful to provide examples of 2 - 3 instances of this concept in your domain. This &lt;a href=&quot;https://en.wikipedia.org/wiki/Extensional_and_intensional_definitions&quot;&gt;outside-in/inside-out approach&lt;/a&gt; helps you check the reality of your domain against your (and your organization’s) assumptions.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/4c635910f72fec00f1546f8dfad931bd338a5143-1316x834.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;760&quot; alt=&quot;Screenshot of a spreadsheet showing a list of concepts, definitions, and examples in the User Experience Design Practices and Techniques domain.&quot; /&gt;&lt;figcaption&gt;Concept definitions and examples in the User Experience Design Practices and Techniques domain.&lt;/figcaption&gt;&lt;/figure&gt;&lt;h3 id=&quot;3-review-and-refine-concepts-and-definitions&quot;&gt;3. Review and Refine Concepts and Definitions&lt;/h3&gt;&lt;p&gt;Your first pass at definitions should be based on research. This is your best assessment of what “accurate” is for a given concept in the context of your domain. The next step is to set up a series of reviews with stakeholders and SMEs to get feedback on your definitions. Structure your discussion to elicit feedback on:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;The relevance of the concepts you’ve identified&lt;/li&gt;&lt;li&gt;The accuracy of your provisional definitions&lt;/li&gt;&lt;li&gt;The accuracy of your provisional set of example instances&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;The goals of reviewing your concepts and definitions &lt;em&gt;prior&lt;/em&gt; to beginning to define the relationships between them are to (a) make sure you’re on the right track and (b) unearth hidden concepts or meanings. Be prepared for your definitions and examples to evolve—possibly significantly.&lt;/p&gt;&lt;p&gt;I prefer to review core concepts in small groups of 2 - 3 participants at similar levels of responsibility in the organization. As you move through each review session with new groups of stakeholders and SMEs, add another column to your Concepts &amp;amp; Definitions spreadsheet for notes.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/5a4b1cdbed99fcf7de2e37a8d843b7f09cccde9d-1300x818.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;755&quot; alt=&quot;Screenshot of a spreadsheet showing a list of concepts, definitions, examples, and review notes in the User Experience Design Practices and Techniques domain.&quot; /&gt;&lt;figcaption&gt;Notes from reviews of concept definitions and examples in the User Experience Design Practices and Techniques domain.&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;Resist the urge to update definitions as you go. Your goal in the review sessions is not to react to individual statements, but rather to build a record of:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;How the organization as a whole thinks about the concepts that are core to its domain&lt;/li&gt;&lt;li&gt;Where there is broad agreement&lt;/li&gt;&lt;li&gt;Where there is inconsistency and internal disagreement on concepts&lt;/li&gt;&lt;li&gt;Where internal understanding of concepts differ significantly from commonly accepted definitions, industry standards, or insights gained from domain and user research&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;After you’ve completed your reviews, now it’s time to revise your definitions. Synthesize the feedback you’ve received, and, where necessary, ask additional questions or draw on additional research. If you find there is broad disagreement on what a concept means, it may be that two (or more) groups are using one word to refer to two (or more) different concepts. Don’t just “do what the boss says”: untangle the layers of meaning in what you’ve found and suggest more nuanced language that can help you and everyone in the organization communicate more clearly and more consistently.&lt;/p&gt;&lt;h3 id=&quot;4-model-domain-relationships&quot;&gt;4. Model Domain Relationships&lt;/h3&gt;&lt;p&gt;Once you have a well-defined and consensus-based set of domain concepts, you can begin to model the consistent, durable relationships between them. In the relationship modeling phase, it can be helpful to think of your “concepts” as domain “objects”: this allows you to expand or contract the units of meaning you’ve identified based on the relationships they have in common.&lt;/p&gt;&lt;p&gt;To begin this process, copy your domain concepts list (just the terms, not the definitions) into a tool that allows you to move objects around spatially and connect them with labeled lines. (&lt;a href=&quot;https://miro.com/&quot;&gt;Miro&lt;/a&gt; is an excellent tool for this).&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/ec89be6f0acc10bfa18d0140d900e6d6acbe69b0-1300x740.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;683&quot; alt=&quot;A boxes-and-arrows diagram showing a draft version of relationships between objects in the User Experience Design Practices and Techniques domain.&quot; /&gt;&lt;figcaption&gt;A rough, working draft-in-process of relationships between objects in the User Experience Design Practices and Techniques domain.&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;As you begin to model relationships, keep these points in mind:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;Domain concept relationship models are &lt;em&gt;not&lt;/em&gt; sitemaps or user flows. Resist the temptation to fit the domain model into those patterns.&lt;/li&gt;&lt;li&gt;Look for the primary relationships between objects. You’re not trying to identify every possible relationship, but rather the connections that define the domain. Look for the connections without which this domain could be (or is) some other domain.&lt;/li&gt;&lt;li&gt;Add or combine concepts until you can describe simple, direct relationships between objects. This can be difficult, especially for the kinds of complex relationships we often encapsulate in language, but it is important for two reasons:&lt;ol&gt;&lt;li&gt;Picking apart complex relationships surfaces hidden domain objects—these are often unstated assumptions the organization has about how something works or tacit rules you’ve yet to uncover. Get these out in the open and make sure there’s agreement on what they are and how they relate to other objects.&lt;/li&gt;&lt;li&gt;The domain model is going to be used to design information structures that allow computers to orchestrate elements of an information system. This is orders of magnitude more straightforward when you’re dealing with binary relationships. Introducing complex, tertiary relationships significantly complicates building a system, and introduces assumptions into relationships that can lead to unexpected behavior later on.&lt;/li&gt;&lt;/ol&gt;&lt;/li&gt;&lt;/ul&gt;&lt;h4 id=&quot;adding-concepts&quot;&gt;Adding Concepts&lt;/h4&gt;&lt;p&gt;If you find it difficult to define a clear, direct relationship between objects, you may be missing an object, or you may have described a concept as a single object that should be multiple objects (because it represents several distinct relationships in the model).&lt;/p&gt;&lt;p&gt;For example, the initial domain concepts list for UX Methods didn’t include a distinct concept to represent the idea of a “Design Problem.” When initially drafting domain relationships, this posed a problem in creating clear, simple relationships between “Outcomes” and “Goals.” Adding a “Design Problem” object helped surface the missing concept and allowed for the creation of direct relationships.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/9871bae1ee829e1602ac691cc70b7e1c87ff992b-1300x740.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;683&quot; alt=&quot;Detail of an added concept in a draft of the User Experience Design Practices and Techniques relationship model showing the object “design problem” having been added to the diagram.&quot; /&gt;&lt;figcaption&gt;Detail of an added concept in a draft of the User Experience Design Practices and Techniques relationship model.&lt;/figcaption&gt;&lt;/figure&gt;&lt;h4 id=&quot;combining-concepts&quot;&gt;Combining Concepts&lt;/h4&gt;&lt;p&gt;Sometimes concepts that have substantive differences in the way they are defined relate to other concepts in the same way. In some of these cases, you can create a clearer and more manageable relationship model by collapsing concepts into a single object or grouping them together.&lt;/p&gt;&lt;p&gt;In the UX Methods domain, “Solution” and “Insight” are distinct concepts. Both concepts, however, relate to adjacent concepts in the model in similar ways.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/a383ef4f4044e533ce2e4a1be779226e926363db-1300x742.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;685&quot; alt=&quot;Detail of combined concepts in a draft of the User Experience Design Practices and Techniques relationship model showing the objects “solution” and “insight” having been combined to a single object, “outcome.”&quot; /&gt;&lt;figcaption&gt;Detail of combined concepts in a draft of the User Experience Design Practices and Techniques relationship model.&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;Combining these concepts creates a simpler model, and creates clarity around the essential relationships between the relevant domain objects. In this case, combining these concepts to the single object “Outcome” led to the insight that both “Solutions” and “Insights” could be accurately described by a single “Input/Output” taxonomy.&lt;/p&gt;&lt;p&gt;👉 &lt;em&gt;To see the final version and applied use of the UX Methods domain model, have a look at the running example in&lt;/em&gt; &lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/insights/structured-content-design-22/&quot;&gt;Structured Content Design 2022&lt;/a&gt;.&lt;/p&gt;&lt;h3 id=&quot;5-review-and-refine-the-relationship-model&quot;&gt;5. Review and Refine the Relationship Model&lt;/h3&gt;&lt;p&gt;As with the domain concepts, it is crucial to review and refine the relationship model with stakeholders and SMEs. In &lt;a href=&quot;https://www.amazon.com/Designing-Connected-Content-Products-Tomorrow/dp/0134763386&quot;&gt;&lt;em&gt;Designing Connected Content&lt;/em&gt;&lt;/a&gt;, Carrie Hane and Mike Atherton recommend drafting a relationship model collaboratively from the start. While this can be a great option in many situations, I have often found that for client work the particularity of the relationship model, as detailed briefly above, means that it is easier and more efficient for feedback providers to react to a draft than to learn how to create a model themselves.&lt;/p&gt;&lt;p&gt;In most cases, in fact, I like to have multiple approaches for stakeholders to respond to. This encourages everyone to adopt a more open mind to how these concepts may relate, and provides additional opportunity to have nuanced discussions that lead to a deeper understanding of the subject domain at hand.&lt;/p&gt;&lt;p&gt;On a recent client project, for instance, I drafted three relationship models from the 23 domain concepts we had collaboratively defined in previous steps, then presented each model to three groups of reviewers for feedback (details of images blurred to protect client confidentiality).&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/35959dd6dd4cae6821fcf0104793d81de0051f2f-1300x1346.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;1242&quot; alt=&quot;A series of relationship model diagrams suggesting the notes and annotations that might be added during the review process.&quot; /&gt;&lt;figcaption&gt;An illustration of the use of relationship model artifacts in the review process.&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;When discussing relationship models with review participants, I also find it helpful to annotate the relationship diagram with numbers to make it easier to discuss particular sections and structures. This is especially useful if you’re conducting your review remotely.&lt;/p&gt;&lt;p&gt;As with the concept review, capture feedback as you go, but don’t actively revise the diagram in the review session. If you’re using Miro, you can use a different colored “sticky note” for each participant so you’ll know where to follow up if you have questions later.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/6b2ba505f91b5db0bec937980c9307440293acfd-1300x738.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;681&quot; alt=&quot;A domain relationship diagram showing numerical annotations used in the review process, as well as notes added during the review.&quot; /&gt;&lt;figcaption&gt;Annotations and notes added to a relationship diagram for review.&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;Once you’ve collected a complete set of feedback, revise your model. As you did with your definitions, synthesize the feedback you’ve received, and, where necessary, ask additional questions or draw on additional research. Dig in to any points of friction or disagreement you find, and if necessary, conduct a second round of reviews to make sure you’ve teased out and accounted for the nuances of your domain.&lt;/p&gt;&lt;h2 id=&quot;next-steps&quot;&gt;Next Steps&lt;/h2&gt;&lt;p&gt;Domain modeling is a valuable tool for discovery, generating alignment, and documenting a shared structural foundation on which subsequent work can be built. While these broad benefits create considerable value throughout the life of a product, for content-focused work the primary “next step” after domain modeling is the design of a &lt;em&gt;content model&lt;/em&gt;.&lt;/p&gt;&lt;p&gt;You can find details on creating content models, as well as how domain modeling fits into a holistic structured content design process in “&lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/insights/structured-content-design-22/&quot;&gt;Structured Content Design Workflow 2022&lt;/a&gt;.” I also highly recommend Hane and Atherton’s &lt;a href=&quot;https://www.amazon.com/Designing-Connected-Content-Products-Tomorrow/dp/0134763386&quot;&gt;&lt;em&gt;Designing Connected Content&lt;/em&gt;&lt;/a&gt;, which provides the foundational model the process I describe here is built on, and gives an approachable, well rounded introduction to, well, “designing connected content.” Sarah Wachter-Boettcher’s &lt;a href=&quot;https://www.amazon.com/Content-Everywhere-Strategy-Structure-Future-Ready/dp/193382087X/&quot;&gt;&lt;em&gt;Content Everywhere&lt;/em&gt;&lt;/a&gt; is also a goldmine of insights and examples of understanding, modeling, and putting content to use.&lt;/p&gt;&lt;h2 id=&quot;acknowledgements-resources&quot;&gt;Acknowledgements &amp;amp; Resources&lt;/h2&gt;&lt;p&gt;Carrie Hane’s and Mike Atherton’s work in structured content spans more than a decade and has had a profound impact on how I understand and practice technical content design. Their book, &lt;a href=&quot;https://www.amazon.com/Designing-Connected-Content-Products-Tomorrow/dp/0134763386&quot;&gt;&lt;em&gt;Designing Connected Content&lt;/em&gt;&lt;/a&gt;, is a must read for anyone designing content systems that need to scale on the modern web. The steps and examples I present here trace a direct lineage back to their insights, and are offered in the spirit of providing an additional viewpoint and further examples for those dipping their toes into domain models for the first time. None of this would have been possible without Carrie’s and Mike’s clear formulation of how domain modeling fits into the larger process and why it is necessary.&lt;/p&gt;&lt;p&gt;&lt;a href=&quot;https://understandinggroup.com/dan-klyn&quot;&gt;Dan Klyn&lt;/a&gt;, information architect and co-founder of &lt;a href=&quot;https://understandinggroup.com/&quot;&gt;The Understanding Group&lt;/a&gt; (TUG), uses the term “ontology” to refer to the particular meaning of a product or service. He describes ontology as “&lt;a href=&quot;https://understandinggroup.com/ia-theory/understanding-information-architecture&quot;&gt;what we mean when we say what we say&lt;/a&gt;.” Dan’s careful and deliberate focus on how hard it is to accurately convey meaning—and how we might overcome those challenges—has been elemental in my understanding of how to design for clarity in our increasingly confusing world. His work is well worth exploring for those seeking to make the complex clear.&lt;/p&gt;&lt;p&gt;Though not focused on content design directly, &lt;a href=&quot;https://adlininc.com/&quot;&gt;Tamara Adlin’s&lt;/a&gt; innovative work on Alignment Personas provides crucial insight into the perils of unaligned teams, and the steps it takes to get everyone pulling in the same direction. Using her alignment persona framework on client projects has helped me understand the outsized rewards of taking explicit steps to align stakeholders and team members, and in turn how to apply that strategy to the process of defining meaning and structuring content.&lt;/p&gt;&lt;p&gt;I’ve written elsewhere about &lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/insights/boutique-knowledge-graphs/&quot;&gt;where structured content design and web semantics and knowledge graphs meet&lt;/a&gt;. The approach I’ve outlined above encourages us to think about and describe &lt;em&gt;content as data&lt;/em&gt; that can be integrated into information systems and mediated, read, and interpreted by machines. Michael Uschold’s &lt;a href=&quot;https://www.amazon.com/Demystifying-Enterprise-Synthesis-Lectures-Semantic/dp/1681731274&quot;&gt;&lt;em&gt;Demystifying OWL for the Enterprise&lt;/em&gt;&lt;/a&gt; provides a cogent and accessible introduction to the design and creation of the formal web ontologies that allow us to express human meaning in a way that is actionable by machines.&lt;/p&gt;&lt;h3 id=&quot;ux-methods-examples&quot;&gt;UX Methods Examples&lt;/h3&gt;&lt;ul&gt;&lt;li&gt;View (and save your own copy of) the &lt;a href=&quot;https://docs.google.com/spreadsheets/d/1iEnsOppv0LuZLTKgBFku1WfsjNIOUz_Dg7fy7emNVDw/edit#gid=1644532379&quot;&gt;UX Methods Concepts &amp;amp; Definitions Google Sheet&lt;/a&gt;&lt;/li&gt;&lt;li&gt;View (and ave your own copy of) the &lt;a href=&quot;https://miro.com/app/board/uXjVMZGjxmI=/?share_link_id=26857243860&quot;&gt;UX Methods Domain Diagram in Miro&lt;/a&gt;&lt;/li&gt;&lt;/ul&gt;</content>
  </entry>
  <entry>
    <title type="text">Boutique Knowledge Graphs: Creating Smart Content at Any Scale</title>
    <link rel="alternate" type="text/html" href="https://preview.andyfitzgeraldconsulting.com/insights/boutique-knowledge-graphs/"/>
    <id>https://preview.andyfitzgeraldconsulting.com/insights/boutique-knowledge-graphs/</id>
    <published>2022-01-20T00:00:00Z</published>
    <updated>2022-01-20T00:00:00Z</updated>
    <summary type="text">An approachable, scalable technique for solving well-defined communication and discovery problems.</summary>
    <category term="Method"/>
    <category term="Structured Content"/>
    <category term="Interoperability"/>
    <category term="Automation"/>
    <category term="Technology Integration"/>
    <category term="Knowledge Graphs"/>
    <content type="html">&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/23d36c3e30cc05a0e4ebf08c1d58cb6bdc4191d8-1300x500.jpg?rect=206,0,888,500&amp;amp;w=888&amp;amp;h=500&amp;amp;fit=crop&amp;amp;auto=format&quot; width=&quot;888&quot; height=&quot;500&quot; alt=&quot;A circular diagram demonstrating the relationships of Sanity, data.world, and Gatsby, among other information processing technol&quot; /&gt;&lt;/figure&gt;&lt;p&gt;By situating data in context, knowledge graphs create valuable opportunities for content creation, recommendation, and management&amp;amp;mdash;even at small scales. A boutique approach to knowledge graph design offers a scalable strategy for starting out small and solving well-defined communication and discovery problems to create measurable value.&lt;/p&gt;&lt;p&gt;A knowledge graph is a collection of real world facts whose properties and relationships are described in ways that machines can process. Knowledge graphs help computers &lt;em&gt;infer&lt;/em&gt; new information that, though it is not explicitly stated in any one data source, is necessarily true given all the facts combined.&lt;/p&gt;&lt;p&gt;Knowledge graphs can capture data about just about anything: products, services, how-tos, and fact sheets are all common use cases. These kinds of data facts are how a search query for “gluten free delivery near me” can return a map of your area and a list of restaurants. Even though the facts about your location, a restaurant’s menu, and whether they (or another service) will deliver food may all come from different sources, when those facts and their relationships are machine readable, a search algorithm is able to provide an answer to your “question” (even though that answer isn’t explicitly published in any one place—and in this case, even though you didn’t even mention “food”).&lt;/p&gt;&lt;p&gt;Search provides just one example of the kinds of interactions knowledge graphs can support. Knowledge graphs also play an increasingly important role in many other industries that grapple with large amounts of information and complexity. Biotech, telecom, finance, and cybersecurity all use knowledge graphs to derive new information from existing data to solve business and user problems.&lt;/p&gt;&lt;p&gt;Though global corporations and search giants offer the most prominent examples, the benefits of knowledge graphs are not limited to enterprise use cases. The situation of &lt;em&gt;data in context&lt;/em&gt; that knowledge graphs provide opens up new opportunities for content personalization and recommendations, content creation, semantic search, and enhanced analytics that can be used by organizations of any size—including those starting out small and seeking to solve a few well-defined communication and discovery problems. I refer to these kinds of applications as “boutique knowledge graphs.”&lt;/p&gt;&lt;h2 id=&quot;the-upside-to-starting-small&quot;&gt;The Upside to Starting Small&lt;/h2&gt;&lt;p&gt;Unlike traditional “monolithic” enterprise IT solutions, knowledge graph technologies invite what &lt;a href=&quot;https://www.semanticarts.com/shacl-and-owl/&quot;&gt;Dave McComb of Semantic Arts&lt;/a&gt; calls a “start small, think big” approach. Two key features of knowledge graphs make this possible:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;&lt;strong&gt;Foundational knowledge graph technologies are built on open W3C semantic web standards.&lt;/strong&gt; Many of the tools that power enterprise-ready software suites are built on a foundation of the same technologies that anyone can use to set up a boutique knowledge graph.&lt;/li&gt;&lt;li&gt;&lt;strong&gt;W3C semantic web standards are designed to work at any scale&lt;/strong&gt;—and to remain effective whether you’re marshaling 200 facts or 2 billion facts. Projects at either end of this spectrum will have very different &lt;em&gt;infrastructure&lt;/em&gt; needs, but the data and relationships represented in each case use the same underlying data model (&lt;a href=&quot;https://www.w3.org/RDF/&quot;&gt;RDF&lt;/a&gt;).&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;Cost, both in terms of financial outlay and the organizational effort needed to stand up an enterprise system, is a common roadblock to beginning work on a knowledge graph. A boutique knowledge graph is a way to start small—and return actual value. This is an appealing approach for many orgs who want to “test the waters” before diving in.&lt;/p&gt;&lt;p&gt;Starting small, however, should not be considered a second tier solution. As &lt;a href=&quot;http://principles-wiki.net/principles:gall_s_law&quot;&gt;systems theorist John Gall&lt;/a&gt; puts it, “A large system that works is invariably composed of smaller systems that work.” Because of the knowledge graph’s innate ability to scale and its foundation in shared tools, beginning with these smaller systems is often a better choice overall.&lt;/p&gt;&lt;h2 id=&quot;boutique-knowledge-graph-design-principles&quot;&gt;Boutique Knowledge Graph Design Principles&lt;/h2&gt;&lt;p&gt;Knowledge graphs have been the subject of an &lt;a href=&quot;https://www.gartner.com/en/articles/the-4-trends-that-prevail-on-the-gartner-hype-cycle-for-ai-2021&quot;&gt;increasing amount of attention&lt;/a&gt; in the last couple years, which has led to a flood of interpretations of what they can do and how to set them up. No single set of heuristics will cover every use case, but if you’re looking for a way to start small, deliver value, and build a foundational system that will work (and work as it scales), the following design principles, drawn from my own experience with client projects, content, and information needs, are a good place to start:&lt;/p&gt;&lt;ol&gt;&lt;li&gt;&lt;strong&gt;Use standards&lt;/strong&gt;&lt;br/&gt;The temptation to adopt &lt;em&gt;ad hoc&lt;/em&gt; or convenient but proprietary data formats can be strong. Standardized data models—such as &lt;a href=&quot;https://www.w3.org/RDF/&quot;&gt;RDF&lt;/a&gt;, &lt;a href=&quot;https://www.w3.org/2004/02/skos/&quot;&gt;SKOS&lt;/a&gt;, and &lt;a href=&quot;https://www.w3.org/OWL/&quot;&gt;OWL&lt;/a&gt;—make data more interoperable and more readily reusable. The little bit of up front effort to adopt standards can save hours and days of headaches later.&lt;/li&gt;&lt;li&gt;&lt;strong&gt;Use unique identifiers&lt;/strong&gt;&lt;br/&gt;Knowledge graphs combine data from different sources. Ensuring that each data point—each fact—can be uniquely identified is crucial to maintaining the integrity of the combined data set as it scales.&lt;/li&gt;&lt;li&gt;&lt;strong&gt;Structure content for reuse&lt;/strong&gt;&lt;br/&gt;Humans excel at extracting facts from blocks of text and other potentially ambiguous formats. In order for machines to do so, that text must first be parsed by natural language processing tools. Even with this extra step, the margin of error in the data returned can be shockingly high. Well structured content describes the facts content communicates and the relationships between those facts in ways that both humans and machines can directly understand.&lt;/li&gt;&lt;li&gt;&lt;strong&gt;Address business needs from the outset&lt;/strong&gt;&lt;br/&gt;Knowledge graphs, like taxonomies, can be built &lt;em&gt;for&lt;/em&gt; a purpose, or &lt;em&gt;of&lt;/em&gt; a subject. When building for a purpose, it is much easier to determine what should be built, identify when it is done, and evaluate the degree to which it is effective. Building a graph representation “of a subject” may have &lt;em&gt;no&lt;/em&gt; realistic endpoint, and may deliver value sporadically, if at all.&lt;/li&gt;&lt;li&gt;&lt;strong&gt;Always think about the next larger context&lt;/strong&gt;&lt;br/&gt;To quote architect &lt;a href=&quot;https://en.wikipedia.org/wiki/Eliel_Saarinen&quot;&gt;Eliel Saarinen&lt;/a&gt;, “Always design a thing by considering it in its next larger context—a chair in a room, a room in a house, a house in an environment, an environment in a city plan.” Keeping in mind the next larger context is why we use standards, unique identifiers, and structured content: each of these anticipates the way the data we capture in the moment will interact with the larger data environment in which it is situated.&lt;/li&gt;&lt;/ol&gt;&lt;h2 id=&quot;a-boutique-knowledge-graph-in-action&quot;&gt;A Boutique Knowledge Graph in Action&lt;/h2&gt;&lt;p&gt;While I’m not at liberty to share examples from client work of these principles in action (for all the usual privacy reasons), a recent redesign of a personal project offers a practical view of how a boutique knowledge graph can add value to a content-focused project at a small scale.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/7634dd0603eb6b5da3f5d878bf139517f93898cb-2600x1700.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;785&quot; alt=&quot;Screenshot of UXMethods.org on desktop and mobile&quot; /&gt;&lt;figcaption&gt;The UXMethods.org website&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;&lt;a href=&quot;https://uxmethods.org/&quot;&gt;UXMethods.org&lt;/a&gt; is a collection of how-tos and web resources aimed at helping UX practitioners more easily discover and connect UX processes and tools. UX Methods combines structured content, open source semantic web technologies, and cloud-based graph data management to create and use a loosely-coupled, goal-focused knowledge graph.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/c3bb8d30d194a8ea0e1004bc1db9f82bc327be52-1300x800.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;738&quot; alt=&quot;A circular diagram illustrating the movement of data from Sanity CMS to data.world, then from Sanity and data.world into the Gatsby static site generator.&quot; /&gt;&lt;figcaption&gt;The UX Methods information ecosystem&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;Key components of the UX Methods information ecosystem include:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;&lt;strong&gt;&lt;a href=&quot;https://www.sanity.io/&quot;&gt;Sanity CMS&lt;/a&gt;:&lt;/strong&gt; A fully decoupled headless CMS that gives content designers wide latitude over the structure and composition of content. Initial UX Methods content types include Methods, Disciplines, and Web Resources (links and metadata about external sites that provide additional information about methods, tools, and approaches).&lt;/li&gt;&lt;li&gt;&lt;strong&gt;&lt;a href=&quot;https://data.world/&quot;&gt;data.world&lt;/a&gt;:&lt;/strong&gt; A cloud-native, graph-based data catalogue. data.world provides APIs for programmatically importing and combining data, and SPARQL endpoints for running aggregated queries across data sets.&lt;/li&gt;&lt;li&gt;&lt;strong&gt;&lt;a href=&quot;https://www.gatsbyjs.com/&quot;&gt;Gatsby&lt;/a&gt;:&lt;/strong&gt; A React-based open source framework for building static JAMStack websites that draw from multiple data sources.&lt;/li&gt;&lt;li&gt;&lt;strong&gt;&lt;a href=&quot;https://docs.github.com/en/actions&quot;&gt;GitHub Actions&lt;/a&gt;:&lt;/strong&gt; A repository-integrated CI/CD workflow automation toolkit.&lt;/li&gt;&lt;li&gt;For details on how to use &lt;em&gt;Structure&lt;/em&gt;, &lt;em&gt;Expression&lt;/em&gt;, and &lt;em&gt;Maturation&lt;/em&gt; concepts to coordinate structured content driven information ecosystems, check out &lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/insights/structured-content-design-22/&quot;&gt;Structured Content Design Workflow 2022&lt;/a&gt;.&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;Even in this narrow and very small scale example, we can find some examples of how the principles above help make for “small systems that work”—and set those systems up to scale to much broader capabilities and capacities:&lt;/p&gt;&lt;h3 id=&quot;using-standards&quot;&gt;Using Standards&lt;/h3&gt;&lt;p&gt;In UX Methods, structured content from Sanity is turned into semantic graph content prior to the site being built in Gatsby. This process serializes Methods content from Sanity’s API as RDF triples (.ttl) and writes them to data.world. A parallel process serializes input/output taxonomy content as SKOS and writes it to a linked dataset.&lt;/p&gt;&lt;p&gt;UX Methods currently doesn’t make use of &lt;a href=&quot;https://www.w3.org/2004/02/skos/&quot;&gt;SKOS&lt;/a&gt; synonyms or broader terms in recommending and ranking content, but by basing this initial implementation on the SKOS standard, a number of modeling and labeling questions are taken care of automatically, and the taxonomy is already set to scale as additional features are added.&lt;/p&gt;&lt;h3 id=&quot;use-of-unique-identifiers&quot;&gt;Use of Unique Identifiers&lt;/h3&gt;&lt;p&gt;The UX Methods Gatsby build process uses content data from two source APIs: the Sanity headless CMS, and inferred graph data from data.world. Sanity provides structured content and assets; data.world provides ranking and recommendation data. In each case, Methods are identified by a unique URI in the format &lt;code&gt;https://uxmethods.org/method/&amp;lt;method&amp;gt;&lt;/code&gt;. This allows each process to identify and correlate the appropriate content values, assets, and data.&lt;/p&gt;&lt;p&gt;Unique identifiers also pave the way for future integrations. Currently, web traffic and search console data is not being programmatically incorporated into the build process or generation of recommendations. Since those values are all keyed to stable and identifiable URIs, however, once there is enough content to warrant the extra level of nuance, integrating that data will follow a predictable set of steps.&lt;/p&gt;&lt;h3 id=&quot;structuring-content-for-reuse&quot;&gt;Structuring Content for Reuse&lt;/h3&gt;&lt;p&gt;The structured content designed and authored in Sanity provides “content as data” that is used in several different ways in the build process of UX Methods:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;Content data is used to produce “Methods” resources, available to site visitors at the method URI&lt;/li&gt;&lt;li&gt;Content data is used to populate the knowledge graph at data.world, which is subsequently used to generate “preparation” and “next steps” recommendations&lt;/li&gt;&lt;li&gt;Structured content and graph data are used in combination to generate schema.org JSON-LD data, which helps search algorithms parse and index content for search results, rich snippets, and smart agent consumption&lt;/li&gt;&lt;/ul&gt;&lt;h3 id=&quot;addressing-business-needs-from-the-outset&quot;&gt;Addressing Business Needs from the Outset&lt;/h3&gt;&lt;p&gt;The knowledge graph backing UX Methods is designed to accomplish two specific tasks: generate recommendations for Method preparation and Method next steps, and generate a prioritized list of “Top Methods” for ranking home page navigation links and weighting search results. These goals simplified the process of designing the taxonomy needed to support the knowledge graph by outlining clear objectives with measurable success metrics&lt;/p&gt;&lt;h3 id=&quot;thinking-about-the-next-larger-context&quot;&gt;Thinking About the Next Larger Context&lt;/h3&gt;&lt;p&gt;Delivering measurable value by addressing business needs early on in the process of developing a knowledge graph need not preclude designing a system that scales. This is one of the unique properties of knowledge graphs that sets them apart from traditional “monolithic” enterprise software. For UX Methods, there are several “larger contexts” which these humble beginnings set it up to support:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;&lt;strong&gt;Elevation of external “web resources” to fully defined objects&lt;/strong&gt;&lt;br/&gt;Right now, external Web Resources are “strings” in the build process, rather than uniquely identifiable “things” in the knowledge graph. A first “next larger context” is to more fully define the additional elements beyond Methods and Disciplines in the UX Methods domain. This context is supported by the existing implementation’s use of standards and unique identifiers and its reuse-ready structured content.&lt;/li&gt;&lt;li&gt;&lt;strong&gt;Expanded application of the UX Methods Input/Output taxonomy&lt;/strong&gt;&lt;br/&gt;The Input/Output taxonomy currently uses only a single hierarchical level to classify content. Extending classification to include parent-child relationships between concepts will allow more nuanced classification and discovery as the UX Methods content set grows. The taxonomy’s SKOS data model paves the way for these more expressive structures.&lt;/li&gt;&lt;li&gt;&lt;strong&gt;Publication of the knowledge graph for broader use&lt;/strong&gt;&lt;br/&gt;The UX Methods knowledge graph is already published for use beyond the UX Methods website as JSON-LD, which makes UX Methods content easier to parse by search algorithms and smart agents (like smart home voice assistants). A larger context of reuse and interoperability involves publishing knowledge graph resources as RDF that supports &lt;a href=&quot;https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation&quot;&gt;HTTP content negotiation&lt;/a&gt;. This will allow UX Methods data to be integrated in and across other knowledge graph applications on the web.&lt;/li&gt;&lt;/ul&gt;&lt;h2 id=&quot;balancing-utility-and-growth&quot;&gt;Balancing Utility and Growth&lt;/h2&gt;&lt;p&gt;When you shift mindset from the “idea of standing up a knowledge graph” in the abstract to focusing on what &lt;em&gt;outcomes&lt;/em&gt; you need to accomplish, it becomes much easier to scope what your knowledge graph needs to support—and to dispassionately ask whether you actually need a knowledge graph at all.&lt;/p&gt;&lt;p&gt;Thanks to the openness of semantic web standards and the inherent scalability of knowledge graph techniques, “thinking big while starting small” with a boutique knowledge graph can be a sensible way to begin to realize the benefits of this rapidly emerging technology.&lt;/p&gt;&lt;h2 id=&quot;learn-more&quot;&gt;Learn More&lt;/h2&gt;&lt;p&gt;There is a lot of content about knowledge graph design, implementation, and use out there, much of it related to particular products and services. While many of these sources offer unique insights into particular use cases, it can be difficult to find neutral sources that focus on producing functional implementations centered on the open W3C standards. Here is a short list of resources I’ve found particularly valuable that offer a good starting point for those new to knowledge graph design and implementation:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;“&lt;a href=&quot;https://open.hpi.de/courses/knowledgegraphs2020&quot;&gt;Knowledge Graphs&lt;/a&gt;,” &lt;a href=&quot;https://open.hpi.de/&quot;&gt;OpenHPI&lt;/a&gt; (free self-paced online course, 6 weeks)&lt;/li&gt;&lt;li&gt;&lt;em&gt;Semantic Web for the Working Ontologist&lt;/em&gt;, Dean Allemang, James Hendler, and Fabien Gandon&lt;/li&gt;&lt;li&gt;&lt;em&gt;Demystifying OWL for the Enterprise&lt;/em&gt;, Michael Uschold&lt;/li&gt;&lt;li&gt;&lt;a href=&quot;https://www.oreilly.com/library/view/learning-sparql-2nd/9781449371449/&quot;&gt;&lt;em&gt;Learning SPARQL&lt;/em&gt;&lt;/a&gt;, Bob DuCharme&lt;/li&gt;&lt;li&gt;&lt;a href=&quot;https://www.bobdc.com/blog/&quot;&gt;Bob DuCharme’s blog&lt;/a&gt;, “mostly on technology for representing and linking information”&lt;/li&gt;&lt;li&gt;&lt;a href=&quot;https://www.amazon.com/Designing-Connected-Content-Products-Tomorrow/dp/0134763386&quot;&gt;&lt;em&gt;Designing Connected Content&lt;/em&gt;&lt;/a&gt;, Carrie Hane and Mike Atherton&lt;/li&gt;&lt;li&gt;“&lt;a href=&quot;https://alistapart.com/article/content-modelling-a-master-skill&quot;&gt;Content Modelling: A Master Skill&lt;/a&gt;,” Rachel Lovinger&lt;/li&gt;&lt;li&gt;“&lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/insights/structured-content-design-22/&quot;&gt;Structured Content Design Workflow 2022&lt;/a&gt;,” Andy Fitzgerald&lt;/li&gt;&lt;/ul&gt;</content>
  </entry>
  <entry>
    <title type="text">Structured Content Design Workflow 2022</title>
    <link rel="alternate" type="text/html" href="https://preview.andyfitzgeraldconsulting.com/insights/structured-content-design-22/"/>
    <id>https://preview.andyfitzgeraldconsulting.com/insights/structured-content-design-22/</id>
    <published>2022-01-12T00:00:00Z</published>
    <updated>2022-01-12T00:00:00Z</updated>
    <summary type="text">Focus on communicating effectively to users, however they choose to access content.</summary>
    <category term="Method"/>
    <category term="Structured Content"/>
    <category term="Prototyping"/>
    <category term="Knowledge Graphs"/>
    <category term="Content Modeling"/>
    <content type="html">&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/1799024dc4e7ea597a1da78f126c2636de4d6e38-2600x1000.jpg?rect=495,0,1778,1000&amp;amp;w=1200&amp;amp;h=675&amp;amp;fit=crop&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;675&quot; alt=&quot;The UX Methods CMS and website on a mobile device, superimposed over design documents and diagrams&quot; /&gt;&lt;/figure&gt;&lt;p&gt;Structured content design focuses on communicating effectively to an organization’s patrons, constituents, and customers, wherever they are and however they choose to access content. While it is the cornerstone of effective, scalable content design for the web, it’s also much more than just a “web” technique: it is a way to prioritize effective communication across contexts.&lt;/p&gt;&lt;p&gt;Structured content design is the process of designing digital resources (like websites and apps) from the content out, as opposed to creating page or screen templates first—then shoehorning content into them right before (or right after) launch. This article will introduce you to a repeatable structured content design process, provide an example of that process in action, discuss how each step scales to different sized projects, and leave you with a set of resources you can use to get started with structured content design.&lt;/p&gt;&lt;p&gt;Since &lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/insights/structured-content-design/&quot;&gt;I first wrote about Structured Content Design in 2019&lt;/a&gt;, I’ve had the good fortune to be able to practice, hone, and evolve this approach with clients. This update for 2022 includes revisions based on what I’ve learned in that time, as well as ways I’ve adapted the approach to better suit the changing role of structured content in modern digital systems.&lt;/p&gt;&lt;p&gt;A structured content approach to digital work has a number of advantages over typical “interface first” processes:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;Website and app designs are optimized for their actual content&lt;/li&gt;&lt;li&gt;Content is created and stored in a way that allows it to be reviewed, displayed, mixed, and remixed across platforms&lt;/li&gt;&lt;li&gt;Structured content works hand in hand with &lt;a href=&quot;https://web.dev/new-responsive/&quot;&gt;component driven architectures&lt;/a&gt; that prioritize user preference, personalization, and adaptability&lt;/li&gt;&lt;li&gt;Content as data is machine actionable, which makes it &lt;a href=&quot;https://alistapart.com/article/conversations-with-robots/&quot;&gt;better prepared for emerging platforms like voice and AI-mediated experiences&lt;/a&gt; (like Siri, Alexa, and Google Home), and facilitates the integration of natural language processing (NLP) and &lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/insights/boutique-knowledge-graphs/&quot;&gt;knowledge graph technologies&lt;/a&gt;&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;More than any individual benefit, however, structured content focuses on communicating effectively to an organization’s patrons, constituents, and customers, wherever and however they choose to access content. While it is the cornerstone of effective, scalable content design for the web, structured content design is much more than a “web” technique: it is a way to prioritize effective communication across contexts.&lt;/p&gt;&lt;h2 id=&quot;the-project&quot;&gt;The Project&lt;/h2&gt;&lt;p&gt;In order to illustrate this workflow in practice, I’ll present the steps I use to design structured content in the context of a recent redesign I conducted for the website &lt;a href=&quot;https://uxmethods.org/&quot;&gt;uxmethods.org&lt;/a&gt;. The &lt;a href=&quot;https://github.com/andybywire/ux-methods-poc&quot;&gt;original UX Methods project&lt;/a&gt;, created in the beginning of 2021, was a &lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/projects/#ux-methods&quot;&gt;proof of concept (POC) for a knowledge graph driven education resource&lt;/a&gt;. Its goal was to help those new to the practice of user experience design explore and understand the purpose-driven connections between UX tools, techniques, and approaches.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/7634dd0603eb6b5da3f5d878bf139517f93898cb-2600x1700.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;785&quot; alt=&quot;Screenshot of UXMethods.org on desktop and mobile&quot; /&gt;&lt;figcaption&gt;The UXMethods.org website&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;While the POC did prove out the viability of using a knowledge graph to infer relationships and hierarchy in a traditional web context, it also demonstrated several critical shortcomings in the original approach:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;The overall structure was &lt;em&gt;of&lt;/em&gt; a subject, not &lt;em&gt;for&lt;/em&gt; a user-centered purpose&lt;/li&gt;&lt;li&gt;The process of adding and updating content involved too many manual steps&lt;/li&gt;&lt;li&gt;The site’s structure, though built into the content at a fundamental level, was too dependent on site contributors remembering and following rules&lt;/li&gt;&lt;li&gt;The site’s interdependent components were too rigidly coupled, resulting in cascading failures in the case of errors&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;In late 2021, I used a structured content design approach to remedy these problems and rebuild UX Methods in a more sustainable, growth-oriented, and user-focused way.&lt;/p&gt;&lt;h2 id=&quot;the-process&quot;&gt;The Process&lt;/h2&gt;&lt;p&gt;At a high level, a structured content design workflow moves through four interconnected phases: Meaning, Structure, Expression, and Maturation. Each phase focuses on particular activities and outputs, each of which influence the other phases in both linear and non-linear ways.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/cf49afc0e4c6e5935197d6b3feac88b386f23031-1300x732.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;676&quot; alt=&quot;A workflow diagram showing the progression between the interconnected phases of meaning, structure, expression, and maturity.&quot; /&gt;&lt;figcaption&gt;The structured content design workflow, updated for 2022&lt;/figcaption&gt;&lt;/figure&gt;&lt;ul&gt;&lt;li&gt;&lt;strong&gt;Meaning&lt;/strong&gt; uses research data and stakeholder insight to understand structure and content resources relative to organization goals and user needs.&lt;/li&gt;&lt;li&gt;&lt;strong&gt;Structure&lt;/strong&gt; defines and maps content resource types and attributes to support clearly defined, goal-oriented organization and user activity.&lt;/li&gt;&lt;li&gt;&lt;strong&gt;Expression&lt;/strong&gt; creates platform-specific modes of access to content resources and functionality in order to meet organization and user goals in context.&lt;/li&gt;&lt;li&gt;&lt;strong&gt;Maturation&lt;/strong&gt; frames the tooling and mindset necessary to measure, evaluate, and iterate meaning, structure, and expression in order to fulfill purpose and vision over time.&lt;/li&gt;&lt;/ul&gt;&lt;h2 id=&quot;meaning&quot;&gt;Meaning&lt;/h2&gt;&lt;p&gt;&lt;em&gt;Use research data to understand structure and content resources relative to organizational goals and user needs.&lt;/em&gt;&lt;/p&gt;&lt;p&gt;Work in the Meaning phase begins with a foundation of design research. This often includes:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;stakeholder and user interviews&lt;/li&gt;&lt;li&gt;content analysis&lt;/li&gt;&lt;li&gt;traffic, behavior, and keyword analysis&lt;/li&gt;&lt;li&gt;website and web app user feedback review&lt;/li&gt;&lt;li&gt;competitive analysis with comparable organizations and products&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;As the motivation for the UX Methods project is born out of my personal experience teaching and practicing user experience design, much of my initial discovery was drawn from feedback provided by students and colleagues. The POC site provided a source of traffic, behavior, and keyword data, as well as an initial corpus of content to audit and evaluate for migration. As part of the redesign process, I also completed a competitive audit of comparable sites to better understand how a resource like UX Methods would fit with similar resources already widely in use.&lt;/p&gt;&lt;p&gt;From these inputs, I drafted a vision statement for the redesigned site, identified site goals and high level metrics with which to track progress toward those goals, and created an actionable set of principles to guide design efforts moving forward.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/cfdd947e2cc502f640debd27b5ef81ae35f091f6-1300x822.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;759&quot; alt=&quot;Document detailing the vision, goals, and design principles for UX Methods&quot; /&gt;&lt;figcaption&gt;UX Methods Vision, Goals, and Design Principles&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;Once these foundational goals and the principles were clear, I created a domain model. In this context a “domain” is “a sphere of knowledge, influence, or activity” (&lt;a href=&quot;https://www.amazon.com/Designing-Connected-Content-Products-Tomorrow/dp/0134763386&quot;&gt;Atherton &amp;amp; Hane&lt;/a&gt;, 33), or, more technically, “the particular context of application for the organizing system being designed and the kinds of interactions with resources it will enable” (&lt;a href=&quot;https://www.amazon.com/Discipline-Organizing-MIT-Press/dp/0262518503&quot;&gt;Glushko&lt;/a&gt;, 319). A domain model helps create clarity around concepts, terms, and relationships important to the content being organized. For client projects, the process of domain modeling also helps create alignment and identify gaps in knowledge and conflicting points of view among stakeholders.&lt;/p&gt;&lt;p&gt;The domain modeling process consists of two equally important steps: identifying and defining the core concepts in the subject domain in question, and then mapping the principal relationships between those concepts.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/66b125978988ca48f3e8fbf22b22434e9ea65c3e-1300x814.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;751&quot; alt=&quot;Screenshot of a spreadsheet showing a list of subject domain concepts, definitions, and revision notes&quot; /&gt;&lt;figcaption&gt;Domain concepts and definitions for UX Methods&lt;/figcaption&gt;&lt;/figure&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/35080a8a288ae09863ea72379531ac7c74f03ae5-1300x720.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;665&quot; alt=&quot;Diagram showing the relationships of domain concepts that make up the UX Methods domain&quot; /&gt;&lt;figcaption&gt;The UX Methods domain model&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;👉 &lt;em&gt;Read more about the details and steps of domain modeling in&lt;/em&gt; &lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/insights/domain-modeling/&quot;&gt;Domain Modeling for Structured Content&lt;/a&gt;.&lt;/p&gt;&lt;p&gt;Once you’ve identified the relevant concepts and their relationships, you can then identify which ones are the most likely content types: the concepts around which reusable structures for common resources across the subject domain should be built. Identifying content types provides a starting point for the content modeling that happens in the next phase, Structure.&lt;/p&gt;&lt;h3 id=&quot;how-does-meaning-scale&quot;&gt;How Does Meaning Scale?&lt;/h3&gt;&lt;p&gt;The Meaning phase focuses on creating an explicit, common understanding and alignment on an organization’s goals, content, and value proposition. Since UX Methods is a personal project, this example doesn’t include the usual cast of stakeholders and teammates that would normally participate in this step. For client projects, however, activities in the Meaning phase are deeply collaborative and deeply iterative. The framing of principles and goals are golden opportunities to have rich, meaningful conversations early on in project work. Meaning tasks can also help to inform and nuance other common discovery phase work, such as persona creation and existing research review and synthesis.&lt;/p&gt;&lt;p&gt;The process of domain modeling is likewise iterative and collaborative. I typically take a first pass at a list of domain concepts and definitions based on my initial research, then conduct a series of reviews with stakeholders and subject matter experts (SMEs) to revise and refine the set. I use the same process for modeling a visual representation of the domain: I typically create three or four candidate models, then review and refine them with stakeholders and SMEs. Creating an initial domain model can also be a good collaborative group exercise.&lt;/p&gt;&lt;h2 id=&quot;structure&quot;&gt;Structure&lt;/h2&gt;&lt;p&gt;&lt;em&gt;Define and map content resource types and attributes to support clearly defined, goal-oriented activity of organizations and users.&lt;/em&gt;&lt;/p&gt;&lt;p&gt;Inputs from the Meaning phase provide the raw material from which to define structure. This foundation provides an informed basis from which to:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;define content types&lt;/li&gt;&lt;li&gt;identify the attributes they share&lt;/li&gt;&lt;li&gt;frame the taxonomic relationships that link them together within the identified subject domain&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;Work in the Structure phase uses the domain model and domain insight created in the Meaning phase to create a content model that details, organizes, and maps content types and relationships. At a high level, the content model can be represented as a simple table that describes the repeatable types that make up the model.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/5f707c8f3fa8208a32792c4470560f970a223a2d-1300x814.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;751&quot; alt=&quot;Screenshot of a spreadsheet showing an overview of the UX Methods content types&quot; /&gt;&lt;figcaption&gt;UX Methods content types&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;Below this simple surface, however, types, attributes, and taxonomies are worked out in detail. These elements provide the connective tissue that holds the structure together and allows it to be articulated effectively across contexts. Content type specifications are where the structure of &lt;em&gt;content as data&lt;/em&gt; is rigorously described.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/0bced1cab17759503abb0bb6f87791af5916e578-1300x814.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;751&quot; alt=&quot;Screenshot of a spreadsheet showing the UX Methods Method content type in detail&quot; /&gt;&lt;figcaption&gt;The UX Methods “Method” content type in detail&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;Content types are informed by the concepts defined in the Meaning phase and by the relationships uncovered in the domain model. This context helps you decide which elements should be represented as individual attributes, and which datatype should be employed to represent those attributes.&lt;/p&gt;&lt;p&gt;While some attributes will call for “primitive” values—a string, like a name or short description, a number, or a true/false (Boolean) value—others may refer to other entities or taxonomy terms. Drafting taxonomy terms and relationships in the Structure phase can give you a good sense of the level of complexity you’ll need to be able to support to describe and interconnect structural elements.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/7a5df45b683cdbe38bc88bbb4b9b7f755b508a4c-1300x814.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;751&quot; alt=&quot;Screenshot of a spreadsheet showing the UX Methods I/O taxonomy&quot; /&gt;&lt;figcaption&gt;A detail of the custom I/O taxonomy used in UX Methods&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;For UX Methods, I created a custom Input/Output taxonomy that provides the semantic connections for making related content recommendations. This taxonomy started off with just 22 terms at two levels, but ideally will grow as the project evolves to scores, if not hundreds of terms. By defining this taxonomy in a standards-compliant way from the start, in this case using the W3C recommended &lt;a href=&quot;https://www.w3.org/TR/skos-reference/&quot;&gt;SKOS&lt;/a&gt; data model, growth potential and interoperability are built in at a foundational level.&lt;/p&gt;&lt;h3 id=&quot;how-does-structure-scale&quot;&gt;How Does Structure Scale?&lt;/h3&gt;&lt;p&gt;The number of content types needed by a given collection depends largely on the scope of its domain, but the process for delineating and describing content models scales proportionally to larger projects. By properly structuring inventory, audit, and content model data, even large content sets and complex models can be analyzed and structured using commonly available, easily accessible tools.&lt;/p&gt;&lt;p&gt;I like to start this process with platform agnostic applications (hence all the spreadsheets) because this helps the content design team focus on the inherent structure of concepts, as opposed to adapting from the start to the varying strengths and weaknesses of specialized software. For all but the smallest organization systems, taxonomies and content types will eventually be managed by a CMS or standalone vocabulary management tool. Starting with a simple representation of structured content makes it easier to export these design foundations in formats specialized tools can import and use, such as CSV or JSON files.&lt;/p&gt;&lt;h2 id=&quot;expression&quot;&gt;Expression&lt;/h2&gt;&lt;p&gt;&lt;em&gt;Create platform-specific modes of access to content resources and functionality in order to meet organization and user goals in context.&lt;/em&gt;&lt;/p&gt;&lt;p&gt;The structure defined in the previous phase provides a foundation for communicating the meaning we defined in the first phase. Since this structure isn’t dependent on a specific platform or technology, it can be used as a starting point from which to express content across any number of contexts.&lt;/p&gt;&lt;p&gt;For UX Methods, the connective tissue between Structure and Expression is a headless CMS. In this case, I built the content model defined above with &lt;a href=&quot;https://www.sanity.io/&quot;&gt;Sanity.io&lt;/a&gt;, which offers a content API that is fully decoupled from the front end. Decoupling content from presentation means I can frame the content editing experience in terms of what the content needs to communicate, as opposed to “how it looks.”&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/2ffb094711e17f0e3460c3b7207e42c47cdeb510-1300x822.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;759&quot; alt=&quot;A screenshot of the UX Methods content editing interface, built with Sanity CMS&quot; /&gt;&lt;figcaption&gt;The UX Methods Sanity CMS interface&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;With a content API in place, the next step is to express this content on the web. For many stakeholders (and practitioners), this will be the first phase that “looks like design.” While it is the first place we begin to sketch out traditional user interfaces, these interfaces are not “the start of design”: they are an articulation of the meaning and structure we’ve already established.&lt;/p&gt;&lt;p&gt;In the case of UX Methods, the most explicit way to move from “content model” to “web user interface” is to use content type attributes, as defined in the content model, to construct &lt;em&gt;block templates&lt;/em&gt;, and then use those these block templates to create &lt;em&gt;priority guides&lt;/em&gt;.&lt;/p&gt;&lt;p&gt;A &lt;strong&gt;block template&lt;/strong&gt; is a simple, prioritized list of the content attributes that will appear in each page type. For UX Methods, I created a block template for each distinct resource page (Method and Discipline) and an index page for taxonomy term listings. Resource page templates mostly contain attributes from a single content type, with selected related content attributes as defined in the content model added in. The index page template presents thematic collections of key attributes across content types to allow users to discover related resources across the site.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/1a3dbb2fd1a08ec7fd03e6ffaa25105ec2628849-2600x1252.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;578&quot; alt=&quot;Block templates for Method and Discipline page types, as well as for a taxonomy index page&quot; /&gt;&lt;figcaption&gt;Block templates for UX methods page types&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;&lt;strong&gt;Priority Guides&lt;/strong&gt; are minimal, content-driven representations of page level content. As &lt;a href=&quot;https://alistapart.com/article/priority-guides-a-content-first-alternative-to-wireframes&quot;&gt;Heleen van Nues and Lennart Overkamp&lt;/a&gt; put it, “a priority guide contains content and elements for a mobile screen, sorted by hierarchy from top to bottom and without layout specifications. The hierarchy is based on relevance to users, with the content most critical to satisfying user needs and supporting user (and company) goals higher up.”&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/0cb00d1af81288d41815efd56fb047378874409c-2600x1520.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;702&quot; alt=&quot;Priority guides for the Method page type&quot; /&gt;&lt;figcaption&gt;Moving from block template to priority guide for the Method page type&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;Mapping attribute contents and priorities in block templates helps verify early on in the design process that the system for expressing content works globally, and that resources are connected in ways that express and are supported by the structure you’ve defined. Once you’re confident this big picture view supports project goals, you can then “expand” your block templates into priority guides, using actual, prioritized content as the foundation of the interface design process.&lt;/p&gt;&lt;p&gt;Because they emerge from the inherent structural connections of domain content, priority guides create an implicit sense of how the content collection “hangs together” by itself. Related content, shared attributes, and shared taxonomy terms all work to create a sense of “aboutness” and interconnection.&lt;/p&gt;&lt;p&gt;Global navigation subsequently makes these connections explicit, and layers in additional opportunities for meaning-making and discovery that go beyond what individual resources can offer at the page level. Moving from priority guides into wireframes is generally a good time to begin layering in global navigation elements. Most modern design tools like Figma and Sketch likewise make it easy to begin testing navigation ideas at this stage with easily assembled clickable prototypes.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/02dd042e57a6e0c3ffab23f45d380391858482d2-2600x1008.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;465&quot; alt=&quot;Mobile and desktop wireframes for the UX Methods website&quot; /&gt;&lt;figcaption&gt;Wireframes with global navigation for UX Methods&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;Clients and colleagues are sometimes surprised that the creation of global navigation occurs this late in the design process. Once we recognize that the primary “connectedness” of the content is embodied in the content itself, however, this order makes perfect sense. It also means that you can design navigation that supports these inherent connections, instead of mandating an arbitrary structure and forcing content to fit into it.&lt;/p&gt;&lt;p&gt;For UX Methods, the visual design was carried over in its entirety from the POC, so moving from wires to page templates in the new build was mostly a question of making sure the HTML was semantically correct and the appropriate CSS was applied.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/26fabdbd040607be9ee5a0946ef97b08fd1edb12-2600x1236.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;570&quot; alt=&quot;Mobile and desktop screen showing the UX Methods web interface visual design&quot; /&gt;&lt;figcaption&gt;UX Methods page-templates-in-process running on a local development server&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;“Pages,” however, aren’t the only way content might be expressed on the web. For UX Methods, in addition to screens, &lt;a href=&quot;https://www.w3.org/standards/semanticweb/data&quot;&gt;Linked Data&lt;/a&gt; was added to the &lt;code&gt;&amp;lt;head&amp;gt;&lt;/code&gt; element of each resource so that search algorithms and digital agents (like Google’s rich results or smart home voice assistants) also have first class access to the content. Method content is also transformed into RDF, which encodes data for use on the Semantic Web, and loaded into a lightweight knowledge graph hosted at &lt;a href=&quot;https://data.world/&quot;&gt;Data.world&lt;/a&gt;.&lt;/p&gt;&lt;p&gt;The addition of expression as RDF makes UX Methods content reusable and interoperable with other semantic web applications. It also introduces a graph database endpoint that can be used to query the UX Methods knowledge graph for inferred insights. These insights are used, for example, in &lt;a href=&quot;https://data.world/andyfitzgerald/ux-methods/workspace/query?queryid=c1e1bcba-5fc8-4fa7-83c4-b03f276ddf30&quot;&gt;selecting and prioritizing “Top Methods” content&lt;/a&gt;, and in &lt;a href=&quot;https://data.world/andyfitzgerald/ux-methods/workspace/query?queryid=aea5b169-bb08-41f6-8091-2a5450f31e09&quot;&gt;keeping “preparation” and “next steps” content in sync and up to date&lt;/a&gt;. Because both Linked Data and RDF are drawn from the same content source and use automated workflows, neither of these additional modes of expressing content create additional work for content creators.&lt;/p&gt;&lt;p&gt;👉 &lt;em&gt;Read more about the integration of structured content and knowledge graphs in&lt;/em&gt; &lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/insights/boutique-knowledge-graphs/&quot;&gt;Boutique Knowledge Graphs: Creating Smart Content at Any Scale&lt;/a&gt;.&lt;/p&gt;&lt;h3 id=&quot;how-does-expression-scale&quot;&gt;How Does Expression Scale?&lt;/h3&gt;&lt;p&gt;Expression is where scaling can differ widely from project to project, and from platform to platform. To express a content set on the web, a small site might need a small team or just one person, as is the case for UX Methods. For a recent county government client with thousands of pages, on the other hand, my team split up the website IA, interaction design, visual design, content migration, and development between a dozen individual contributors.&lt;/p&gt;&lt;p&gt;As with other steps in this process, Expression will often require additional tools from the UX skill set. User flows and use cases, prototyping and usability testing, tree testing, and other iterative and evaluative methods are all potentially on the table. The steps described here are not intended to supplant user centered design best practices, but rather to integrate with them to bring structured content into workflows early and use it as an asset in the design process.&lt;/p&gt;&lt;h2 id=&quot;maturation&quot;&gt;Maturation&lt;/h2&gt;&lt;p&gt;&lt;em&gt;Measure, evaluate, and iterate meaning, structure, and expression in order to fulfill purpose and vision over time.&lt;/em&gt;&lt;/p&gt;&lt;p&gt;The goal setting and metrics definition done in the Meaning phase of a structured content design approach provide the core elements for setting up a long term plan for the evolution and continued success of a content collection. I used to think of this phase as “optimization” or “performance evaluation,” but I’ve found that these terms can focus too narrowly on how well a particular &lt;em&gt;tool&lt;/em&gt; works, for example a CMS or a front end, often at the expense of obscuring how well that tool works &lt;em&gt;for the system as a whole&lt;/em&gt; at any given point in time.&lt;/p&gt;&lt;p&gt;For UX Methods, a key strategy for ensuring that its “system as a whole” can mature over time is its &lt;a href=&quot;https://cloud.google.com/learn/what-is-microservices-architecture&quot;&gt;microservices architecture&lt;/a&gt;. Each of the elements that make up an expression of the content a user might interact with are “&lt;a href=&quot;https://en.wikipedia.org/wiki/Loose_coupling&quot;&gt;loosely coupled&lt;/a&gt;” with open, standards-based technologies:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;&lt;strong&gt;Content API:&lt;/strong&gt; Sanity, &lt;a href=&quot;https://www.sanity.io/guides/introduction-to-portable-text&quot;&gt;Portable Text&lt;/a&gt;&lt;/li&gt;&lt;li&gt;&lt;strong&gt;Open data communication standards:&lt;/strong&gt; GraphQL, RDF, SPARQL&lt;/li&gt;&lt;li&gt;&lt;strong&gt;Component-based front end:&lt;/strong&gt; React, Gatsby&lt;/li&gt;&lt;li&gt;&lt;strong&gt;Serverless functions:&lt;/strong&gt; GitHub Actions, Webhooks, Javascript&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;By not relying heavily on one technology, service, or tool, the redesigned approach creates a more resilient system open to change. Each of these tools were chosen for its ability to represent a structure needed to communicate an intended meaning in a given context. Because the connections between them are loose, the system as a whole can be altered without causing the whole to crumble.&lt;/p&gt;&lt;h3 id=&quot;how-does-maturation-scale&quot;&gt;How Does Maturation Scale?&lt;/h3&gt;&lt;p&gt;Just as with each phase in this workflow, the Maturation phase is rooted in the goal of communicating effectively across contexts. Since the goals, content, and contexts of projects are bound to differ wildly, the steps taken to evolve a particular effort are likewise bound to be highly variable—and perhaps not easily anticipated from the outset.&lt;/p&gt;&lt;p&gt;By keeping these larger goals at the forefront of technology, monitoring, and performance optimization decisions, content designers can help business stakeholders define and support a clear vision of what their content needs to achieve—and avoid getting mired in blind allegiance to a particular platform or technology.&lt;/p&gt;&lt;h2 id=&quot;outcomes&quot;&gt;Outcomes&lt;/h2&gt;&lt;p&gt;To a casual observer, the difference between the before and &lt;a href=&quot;https://uxmethods.org/&quot;&gt;after&lt;/a&gt; of the UX Methods redesign should be largely unremarkable. Since neither the overall app nor visual design were issues with the site to begin with, this is as it should be.&lt;/p&gt;&lt;p&gt;The structure and expression used to communicate the site’s meaning, however, are completely reimagined and rebuilt. Each of these are now framed to support sustainable, incremental maturation over time. To revisit the set of shortcomings of the POC listed earlier:&lt;/p&gt;&lt;ol&gt;&lt;li&gt;&lt;strong&gt;Content and site semantics are now focused on user outcomes as defined in the project vision statement.&lt;/strong&gt; This meant scaling back the degree to which the field of user experience was documented, and focusing on the elements that will help users connect methods in practice. UX “disciplines” are still listed, but they are no longer elevated in site and page level navigation, or in the underlying knowledge graph that drives recommendations. Related resources, next steps, and visual wayfinding are prioritized.&lt;/li&gt;&lt;li&gt;&lt;strong&gt;Publication of content, related resources, and knowledge graph data is now completely automated.&lt;/strong&gt; Whereas the POC required a manual build and push process to update content and its underlying semantics, the revised version automates all of these processes in loosely coupled serverless functions. Because each element of the system is connected with open, standards-based protocols, altering or adding to automation workflows is not constrained by a single service or bottleneck, as is often the case in tightly coupled systems.&lt;/li&gt;&lt;li&gt;&lt;strong&gt;Creating well structured content is now the path of least resistance.&lt;/strong&gt; The UX Methods POC—like many client projects I’ve been called in to help with—depended too heavily on content creators remembering steps and making the correct decisions when authoring content. Even with the best intentions, this inevitably leads to errors. Adopting a decoupled, customizable CMS (Sanity, in this case) has made it possible to capture the correct level of structure for the effective expression of content across contexts.&lt;/li&gt;&lt;li&gt;&lt;strong&gt;Loosely coupled microservices are built for resilience and evolution.&lt;/strong&gt; The new version of UX Methods is still missing some key elements related to its primary goals, particularly when it comes to inviting participation and feedback. The new site’s microservices architecture and component-base design mean that work to layer these elements in can be done in parallel with regular content contribution (as opposed to grinding the whole thing to a halt while changes are being rolled out).&lt;/li&gt;&lt;/ol&gt;&lt;h2 id=&quot;resources-and-getting-started&quot;&gt;Resources and Getting Started&lt;/h2&gt;&lt;p&gt;For reference and as a guide to help those who would like to dig deeper into these concepts, here is a summary of the sources I’ve referenced above, plus a few more that have indirectly influenced how I think about and practice structured content design:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;&lt;a href=&quot;https://www.amazon.com/Designing-Connected-Content-Products-Tomorrow/dp/0134763386&quot;&gt;Designing Connected Content&lt;/a&gt;, Carrie Hane and Mike Atherton&lt;/li&gt;&lt;li&gt;&lt;a href=&quot;https://www.amazon.com/Discipline-Organizing-MIT-Press/dp/0262518503&quot;&gt;The Discipline of Organizing&lt;/a&gt;, Robert J. Glushko (Editor)&lt;/li&gt;&lt;li&gt;&lt;a href=&quot;https://www.amazon.com/Content-Everywhere-Strategy-Structure-Future-Ready/dp/193382087X&quot;&gt;Content Everywhere&lt;/a&gt;, Sara Wachter-Boettcher&lt;/li&gt;&lt;li&gt;&lt;a href=&quot;https://abookapart.com/products/content-strategy-for-mobile&quot;&gt;Content Strategy for Mobile&lt;/a&gt;, Karen McGrane&lt;/li&gt;&lt;li&gt;&lt;a href=&quot;https://abookapart.com/products/the-elements-of-content-strategy&quot;&gt;The Elements of Content Strategy&lt;/a&gt;, Erin Kissane&lt;/li&gt;&lt;li&gt;&lt;a href=&quot;https://www.amazon.com/Content-Strategy-Web-Kristina-Halvorson/dp/0321808304&quot;&gt;Content Strategy for the Web&lt;/a&gt;, Kristina Halvorson and Melissa Rach&lt;/li&gt;&lt;li&gt;“&lt;a href=&quot;https://alistapart.com/article/content-modelling-a-master-skill&quot;&gt;Content Modelling: A Master Skill&lt;/a&gt;,” Rachel Lovinger&lt;/li&gt;&lt;li&gt;“&lt;a href=&quot;https://alistapart.com/article/priority-guides-a-content-first-alternative-to-wireframes&quot;&gt;Priority Guides: A Content-First Alternative to Wireframes&lt;/a&gt;,” Heleen van Nues and Lennart Overkamp&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;Here is a list of the tools I’ve used on this project. Your tool set should of course be based on your project needs—and there are a lot of good options out there—but these have worked well for me:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;&lt;a href=&quot;https://www.sanity.io/&quot;&gt;Sanity&lt;/a&gt;&lt;/li&gt;&lt;li&gt;&lt;a href=&quot;https://www.gatsbyjs.com/&quot;&gt;Gatsby&lt;/a&gt;&lt;/li&gt;&lt;li&gt;&lt;a href=&quot;https://graphql.org/&quot;&gt;GraphQL&lt;/a&gt;&lt;/li&gt;&lt;li&gt;&lt;a href=&quot;https://data.world/&quot;&gt;Data.world&lt;/a&gt;&lt;/li&gt;&lt;li&gt;&lt;a href=&quot;https://www.w3.org/TR/sparql11-overview/&quot;&gt;SPARQL&lt;/a&gt;&lt;/li&gt;&lt;li&gt;&lt;a href=&quot;https://docs.github.com/en/actions&quot;&gt;GitHub Actions&lt;/a&gt;&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;This approach and case study reflects the insight and advice of dozens of colleagues and innovators, as well as my own threading together and evolution of these techniques. I’ve endeavored to give appropriate credit wherever it is due above. If I’ve misrepresented, mis-attributed, or otherwise left something or someone out, please do let me know and I’ll correct it posthaste!&lt;/p&gt;</content>
  </entry>
  <entry>
    <title type="text">Self-Hosting Sanity Studio with GitHub Actions</title>
    <link rel="alternate" type="text/html" href="https://preview.andyfitzgeraldconsulting.com/insights/self-hosting-sanity-studio/"/>
    <id>https://preview.andyfitzgeraldconsulting.com/insights/self-hosting-sanity-studio/</id>
    <published>2022-01-05T00:00:00Z</published>
    <updated>2022-01-05T00:00:00Z</updated>
    <summary type="text">A comprehensive guide to self-hosting Sanity Studio on DreamHost with GitHub Actions for continuous integration.</summary>
    <category term="Method"/>
    <category term="Automation"/>
    <category term="Technology Integration"/>
    <content type="html">&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/661e31a64c24d68c0bdc159e77bc6ac24fd088bf-1300x500.jpg?rect=206,0,888,500&amp;amp;w=888&amp;amp;h=500&amp;amp;fit=crop&amp;amp;auto=format&quot; width=&quot;888&quot; height=&quot;500&quot; alt=&quot;A three logo lockup of Sanity, GitHub Actions, and Dreamhost logos&quot; /&gt;&lt;/figure&gt;&lt;p&gt;Sanity Studio offers a fantastic open source structured content editor that can be hosted anywhere. This comprehensive guide provides detailed steps on self-hosting Sanity Studio on DreamHost with continuous development using GitHub actions.&lt;/p&gt;&lt;p&gt;&lt;a href=&quot;https://www.sanity.io/&quot;&gt;Sanity.io&lt;/a&gt; provides an amazingly flexible and adaptable content API for modern &lt;a href=&quot;https://jamstack.org/what-is-jamstack/&quot;&gt;JAMStack&lt;/a&gt; web applications. It also provides an equally remarkable open source content editor for structuring and creating that content: &lt;a href=&quot;https://www.sanity.io/studio&quot;&gt;Sanity Studio&lt;/a&gt;. This article will show you how to deploy and self-host Sanity Studio on your own project subdomain using &lt;a href=&quot;https://docs.github.com/en/actions&quot;&gt;GitHub Actions&lt;/a&gt;. I’ll use &lt;a href=&quot;https://www.dreamhost.com/&quot;&gt;DreamHost&lt;/a&gt; as an example hosting provider, but these are generic steps: you should be able to use any service that provides shell access. (And don’t panic if “shell access” sounds like some crazy hacker nonsense: I’m going to explain each step in excruciating detail).&lt;/p&gt;&lt;p&gt;A project’s Sanity Studio can be &lt;a href=&quot;https://www.sanity.io/docs/deployment#bd4e07db3e37&quot;&gt;deployed with one command directly to a sanity.io subdomain&lt;/a&gt;, or with just a little bit more fanfare &lt;a href=&quot;https://maxkarlsson.dev/blog/how-to-setup-a-self-hosted-sanity-studio&quot;&gt;to a service like Netlify&lt;/a&gt;. These are both good options if you need something quick and adding another hosted service to your project doesn’t matter to you. Hosting Sanity Studio on your own server takes a little more time to set up, but give you control over the entire build process and keeps the addition of new tools, services, and potential subscription fees to a minimum. There’s also something enticingly tidy about keeping one’s CMS in the same domain as the site it supports.&lt;/p&gt;&lt;p&gt;This guide will show you how to:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;Use your existing hosting service and URL&lt;/li&gt;&lt;li&gt;Deploy the studio to a subdomain of your production site (like “studio.yourawesomesite.com”)&lt;/li&gt;&lt;li&gt;Automatically update your studio when you push changes to your studio GitHub repository&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;I’m not going to lie: there are a lot of steps here.&lt;/p&gt;&lt;p&gt;But: if you take them one at a time and make sure things work correctly along the way (which I’ll show you how to do), you’ll have a set-up that takes care of a lot of the minutia for you—and have a better understanding of how you can wield the powers of SSH, shell permissions, and GitHub Actions (and its &lt;em&gt;Secrets&lt;/em&gt;) for the greater good.&lt;/p&gt;&lt;p&gt;On board? Here’s what we’re going to do:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;Set up a subdomain &amp;amp; password-less login on DreamHost&lt;/li&gt;&lt;li&gt;Set up a workflow on GitHub Actions&lt;/li&gt;&lt;li&gt;Add studio permissions on Sanity Admin&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;For an example of what each of these steps look like, I’ll keep each of them in the context of &lt;a href=&quot;https://uxmethods.org/&quot;&gt;UXMethods.org&lt;/a&gt;. UX Methods is a Sanity-driven JAMStack site that uses all of these steps. It is also run from a &lt;a href=&quot;https://github.com/andybywire/ux-methods&quot;&gt;completely open repository on GitHub&lt;/a&gt;, so you can peek into any part of it for an in-the-wild view of how all this works.&lt;/p&gt;&lt;p&gt;&lt;strong&gt;&lt;em&gt;Note:&lt;/em&gt;&lt;/strong&gt; These instructions are Mac and DreamHost focused, but should apply with minor variation to other contexts. If you would like to adapt these to different contexts, like Windows, or a hosting provider that requires additional steps, please let me know. You’re more than welcome to copy everything else I’ve done here (with due credit, naturally), and I’ll link to your version in this note.&lt;/p&gt;&lt;p&gt;&lt;strong&gt;&lt;em&gt;Another note:&lt;/em&gt;&lt;/strong&gt; I pulled from a bunch of other tutorials, guides, manuals, and specs to put these steps together. Where appropriate I’ll link to those sources. I’ll also, where appropriate, provide you with additional details I wish some of those sources would have provided. I’ll call these out in context, so if this background isn’t interesting to you, you should have a good sense of what you can safely skip over. 👍&lt;/p&gt;&lt;h2 id=&quot;set-up-a-subdomain-and-password-less-log-in-on-dreamhost&quot;&gt;Set Up a Subdomain and Password-less Log-In on Dreamhost&lt;/h2&gt;&lt;p&gt;Our first step is to create a subdomain for Sanity Studio and configure SSH (Secure Shell) access so that we can get the robots to keep things up to date for us. Here’s what we’re going to do:&lt;/p&gt;&lt;ol&gt;&lt;li&gt;Create subdomain &amp;amp; user&lt;/li&gt;&lt;li&gt;Set up shell permissions&lt;/li&gt;&lt;li&gt;Generate named keys&lt;/li&gt;&lt;li&gt;Write our public key to an authorized_keys file&lt;/li&gt;&lt;li&gt;Set permissions&lt;/li&gt;&lt;li&gt;Add a config file&lt;/li&gt;&lt;/ol&gt;&lt;p&gt;DreamHost has published their own &lt;a href=&quot;https://help.dreamhost.com/hc/en-us/articles/216499537&quot;&gt;instructions for the password-less log-in steps&lt;/a&gt; in this flow. Those instructions boggled my mind a bit the first few times I tried them, so I’ll break down the steps and commands in more detail here so you can better understand what’s going on.&lt;/p&gt;&lt;h3 id=&quot;1-create-a-subdomain-and-user&quot;&gt;1. Create a Subdomain and User&lt;/h3&gt;&lt;p&gt;Our very first step is to create a subdomain of our main URL. We’ll use this to access Sanity Studio. In this case, https://studio.uxmethods.org will be the place content contributors go to modify content on http://uxmethods.org. DreamHost makes creating a subdomain of a domain you already own pretty simple. Log in to &lt;a href=&quot;https://panel.dreamhost.com/&quot;&gt;https://panel.dreamhost.com&lt;/a&gt;, go to domains, then manage domains, and click “Add Hosting to Domain / Sub-Domain.”&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/87d5873c56d7cff9329edbd70720effd016e5b1e-1300x790.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;729&quot; alt=&quot;Screenshot of DreamHost Hosted Domains admin panel&quot; /&gt;&lt;/figure&gt;&lt;p&gt;Type your subdomain and domain in the “Domain to host:” field, then create a new user in the “Users, Files, and Paths” section:&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/a7fc8cc0b9c2b634b8fd894f2b74af8976cf4f56-1300x790.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;729&quot; alt=&quot;Creating a new user on DreamHost&quot; /&gt;&lt;/figure&gt;&lt;p&gt;Creating a new user means that if your password or login are ever compromised, only this subdomain will be affected. It’s a simple extra step to take to ensure a reasonable level of security for any other domains you’re working with. Hit the “Fully host this domain” button at the bottom of this section to add the subdomain.&lt;/p&gt;&lt;p&gt;The next screen will give you a confirmation message, as well as a password for your new user. Copy this password down someplace handy—you’ll need it soon. Scroll down to your “Hosted domains” list. You should see your subdomain and new user there. The listing will have a little clock next to it until it’s all sorted out in the system.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/109810332b1493131e1349d9ec47efdd7c794def-1300x790.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;729&quot; alt=&quot;Screenshot of DreamHost Manage Domains admin dashboard&quot; /&gt;&lt;/figure&gt;&lt;h3 id=&quot;2-add-shell-user-access&quot;&gt;2. Add Shell User Access&lt;/h3&gt;&lt;p&gt;Once your user and domain are sorted (i.e. the clock is gone when you refresh), click the user link and set the user type to “Shell user.” This will allow you to log in via the command line—and run CLI commands from GitHub Actions. You’ll see a success message and a note that the changes will take a few minutes to take effect. While that’s happening, we’re going to open the terminal and create some keys and permissions.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/55d77c3208c73d7c1c06a85839dc69b6ec66c276-1300x790.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;729&quot; alt=&quot;Screenshot of Edit User panel on DreamHost&quot; /&gt;&lt;/figure&gt;&lt;h3 id=&quot;3-create-an-rsa-keypair&quot;&gt;3. Create an RSA Keypair&lt;/h3&gt;&lt;p&gt;An RSA Keypair is a set of encryption keys you can use to authenticate sessions between systems—for example between your computer and DreamHost servers, or between GitHub Actions and DreamHost servers. (“RSA” is an &lt;a href=&quot;https://en.wikipedia.org/wiki/RSA_(cryptosystem)&quot;&gt;acronym of the names of the dudes who came up with it&lt;/a&gt; in the 70’s). We’re going to create the keypair in the Mac terminal. We’ll then upload one of those keys to DreamHost in the next step.&lt;/p&gt;&lt;p&gt;To create a keypair, &lt;a href=&quot;https://www.youtube.com/watch?v=aKRYQsKR46I&quot;&gt;open the terminal&lt;/a&gt; and follow these steps:&lt;/p&gt;&lt;h4 id=&quot;i-generate-the-key&quot;&gt;&lt;strong&gt;i.&lt;/strong&gt; Generate the key:&lt;/h4&gt;&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;$ ssh-keygen -t rsa&lt;/code&gt;&lt;/pre&gt;&lt;ul&gt;&lt;li&gt;&lt;code&gt;ssh-keygen&lt;/code&gt; is a build in tool for creating authentication keys&lt;/li&gt;&lt;li&gt;the &lt;code&gt;-t&lt;/code&gt; option tells the command that you want a specific type of key&lt;/li&gt;&lt;li&gt;&lt;code&gt;rsa&lt;/code&gt; is the type of key we’re looking for&lt;/li&gt;&lt;li&gt;&lt;strong&gt;&lt;em&gt;Terminal Tip:&lt;/em&gt;&lt;/strong&gt; don’t type the “$” in the command, or in any of the commands listed below. The “$” is a convention for the prompt in your terminal. Your prompt may be different; that’s okay, too (mine is a %).&lt;/li&gt;&lt;/ul&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/ecd6f6d9792ccc4dadfd77a67b9f8bbf0cd70742-1300x788.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;727&quot; alt=&quot;Screenshot of a terminal window showing the generation of an RSA key pair&quot; /&gt;&lt;/figure&gt;&lt;h4 id=&quot;ii-give-the-key-a-name&quot;&gt;ii. Give the key a name:&lt;/h4&gt;&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;/Users/ANDYFITZGERALD/.ssh/sanity_cms&lt;/code&gt;&lt;/pre&gt;&lt;ul&gt;&lt;li&gt;By default, the key id-rsa will be created, but when you have multiple keys (for different users), you’ll want to give them unique and memorable names. I recommend giving the key the same name as the user name you created on DreamHost—in this example, I’m naming the key “sanity_cms”&lt;/li&gt;&lt;li&gt;&lt;strong&gt;&lt;em&gt;Terminal Tip:&lt;/em&gt;&lt;/strong&gt; I’m following the convention that text that will be different on your system is represented here in ALL CAPS. Be sure to change &lt;code&gt;ANDYFITZGERALD&lt;/code&gt; to whatever your user directory is (and make it lower-case).&lt;/li&gt;&lt;li&gt;The user directory shortcut &lt;code&gt;~/&lt;/code&gt; doesn’t work with ssh-keygen, so you have to use the full path. (I don’t know why. If you do, please let me know in a comment!)&lt;/li&gt;&lt;/ul&gt;&lt;h4 id=&quot;iii-leave-the-passphrase-field-empty-just-press-return-twice&quot;&gt;iii. Leave the passphrase field empty—just press return twice.&lt;/h4&gt;&lt;ul&gt;&lt;li&gt;Since we’ll be using this for an automated workflow, we don’t want a passphrase here. Just press return twice to move through this question. As &lt;a href=&quot;https://www.ssh.com/academy/ssh/copy-id#how-ssh-copy-id-works&quot;&gt;ssh.com&lt;/a&gt; notes, “Keys without a passphrase are useful for fully automated processes. They allow shell scripts, programs, and management tools to log into servers unattended.”&lt;/li&gt;&lt;li&gt;You’ll see a key fingerprint and some rando bot-art. Feel free to marvel, though no need to copy this down.&lt;/li&gt;&lt;/ul&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/63b2e0f3684db051333edafb976d11f2241077dd-1300x788.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;727&quot; alt=&quot;Screenshot of a terminal window showing the randomart image generated as the result of RSA key pair creation&quot; /&gt;&lt;/figure&gt;&lt;h3 id=&quot;4-add-the-public-key-to-dreamhost&quot;&gt;4. Add the Public Key to Dreamhost&lt;/h3&gt;&lt;p&gt;What you just created is called a “keypair” because there are two corresponding keys: a private key, that you’ll use to gain access to the DreamHost server, and a public key, that you’ll upload to DreamHost. This is how the server knows to let you in (i.e. if you have the right corresponding private key to its public key).&lt;/p&gt;&lt;p&gt;To copy the public key to DreamHost, run this command:&lt;/p&gt;&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;$ cat ~/.ssh/SANITY_CMS.pub | ssh SANITY_CMS@JACKSONVILLE.dreamhost.com &quot;mkdir ~/.ssh; cat &amp;gt;&amp;gt; ~/.ssh/authorized_keys&quot;&lt;/code&gt;&lt;/pre&gt;&lt;p&gt;Here’s a breakdown of what’s going on here:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;&lt;code&gt;cat&lt;/code&gt; is short for “concatenate.” This command is super common and allows us to create single or multiple files, view content of a file, concatenate files, and redirect output.&lt;/li&gt;&lt;li&gt;The path following the cat command points to the &lt;em&gt;public&lt;/em&gt; key of the RSA keypair we just created (in this case we can use the &lt;em&gt;~/&lt;/em&gt; user directory shortcut)&lt;/li&gt;&lt;li&gt;The “pipe” between that and the next command connects the standard output of the left command to the standard input of the right command&lt;/li&gt;&lt;li&gt;&lt;code&gt;ssh SANITY_CMS@JACKSONVILLE.dreamhost.com&lt;/code&gt; uses SSH to log into your user directory on DreamHost (the one we created earlier)&lt;ul&gt;&lt;li&gt;Be sure to change the part just before the @ to your key’s name&lt;/li&gt;&lt;li&gt;The name after @ is your server. Be sure to change this to your server name. (Check here for &lt;a href=&quot;https://help.dreamhost.com/hc/en-us/articles/115000675027-FTP-overview-and-credentials&quot;&gt;how to find your server name&lt;/a&gt;)&lt;/li&gt;&lt;/ul&gt;&lt;/li&gt;&lt;li&gt;&lt;code&gt;&amp;quot;mkdir ~/.ssh; cat &amp;gt;&amp;gt; ~/.ssh/authorized_keys&amp;quot;&lt;/code&gt; creates a directory named .ssh, and then appends your public key to the file “authorized_keys”&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;If this is your first time connecting to this server, you’ll see this authentication verification. Respond with “yes”:&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/ad590eaced0cb2e8c180a8537c765cff06a6553b-1300x788.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;727&quot; alt=&quot;Screenshot of a terminal window showing the known-hosts authentication dialogue&quot; /&gt;&lt;/figure&gt;&lt;p&gt;You’ll be asked for the password we created earlier.&lt;/p&gt;&lt;ul&gt;&lt;li&gt;If your password gets denied, see the troubleshooting section at the end of this article.&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;You can test that your keys are properly configured by logging in with SSH:&lt;/p&gt;&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;$ ssh -i ~/.ssh/sanity_cms sanity_cms@jacksonville.dreamhost.com&lt;/code&gt;&lt;/pre&gt;&lt;ul&gt;&lt;li&gt;&lt;code&gt;ssh&lt;/code&gt; is our Secure Shell command, the &lt;code&gt;-i&lt;/code&gt; option specifies the identity key (private key) to use for authentication. In this case, it’s the private key we created earlier.&lt;/li&gt;&lt;li&gt;Be sure to swap out your key and server name&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;When you’re successfully logged in, you’ll see a confirmation ASCII art image, and your terminal prompt will change to [SERVER]$&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/f8b5e453b5b10c0480b3f0123f271d6840f4a2da-1300x732.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;676&quot; alt=&quot;Screenshot of a terminal window showing the ASCII art generated when DreamHost has successfully been logged in to via SSH&quot; /&gt;&lt;/figure&gt;&lt;p&gt;Not working as expected? See the troubleshooting section at the end of this article.&lt;/p&gt;&lt;h3 id=&quot;5-set-permissions&quot;&gt;5. Set Permissions&lt;/h3&gt;&lt;p&gt;The commands we just executed created a new folder under your DreamHost user named /.ssh with 755 permissions. 755 means that everyone can read and execute the file, and you (the owner) are allowed to write to the file as well. The “authorized_keys” file has 644 permissions, which means that you (the owner of the file) have read and write access, while the group members and other users on the system only have read access. DreamHost recommends changing these to 700 (full access for you, the owner, no access to anyone else) and 600 (full read and write access to the file for you, no access to anyone else) respectively.&lt;/p&gt;&lt;p&gt;Since we logged in to the DreamHost server in the last step, we can change file permissions from the terminal now with two commands:&lt;/p&gt;&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;$ chmod 700 ~/.ssh $ chmod 600 ~/.ssh/authorized_keys&lt;/code&gt;&lt;/pre&gt;&lt;p&gt;Modifying permissions is a super common command line task. Here’s how these commands work:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;&lt;code&gt;chmod&lt;/code&gt; is the command to change file permissions&lt;/li&gt;&lt;li&gt;The number following the command is the permission level to set&lt;/li&gt;&lt;li&gt;The path following the permission is the file whose permissions we’re changing&lt;/li&gt;&lt;/ul&gt;&lt;h3 id=&quot;6-add-a-config-file-optional&quot;&gt;6. Add a Config File (Optional)&lt;/h3&gt;&lt;p&gt;This last step is optional, but makes logging in from your local terminal a lot easier. The reason we needed to use &lt;code&gt;ssh -i [key] [login address]&lt;/code&gt; earlier is because we added a &lt;em&gt;named&lt;/em&gt; key to our .ssh folder. If you don’t name the key, SSH will simply name it id_rsa, and will then look for that key when you use SSH to log in.&lt;/p&gt;&lt;p&gt;This is fine if you only ever log in one place, or log in everywhere with the same identity. As you might imagine, this poses a security risk if you have multiple domains, for example a domain running production, and a subdomain running your CMS (as I’m proposing here). If the security of one of those is compromised, the security of both is compromised. This gets riskier the more you use the same user (and authentication key) for multiple domains, properties, and projects.&lt;/p&gt;&lt;p&gt;One solution to this security concern is to create a new user for each domain. Having to type &lt;code&gt;ssh -i [key] [login address]&lt;/code&gt; every time you want to log in, however, is a pain. This is what the SSH “config” file is for. It tells SSH which private key to use for each domain. It also lets you set up an alias, so instead of typing&lt;/p&gt;&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;$ ssh -i ~/.ssh/sanity_cms sanity_cms@jacksonville.dreamhost.com&lt;/code&gt;&lt;/pre&gt;&lt;p&gt;or even&lt;/p&gt;&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;$ ssh sanity_cms@jacksonville.dreamhost.com&lt;/code&gt;&lt;/pre&gt;&lt;p&gt;you can just type &lt;code&gt;$ ssh sanity_cms&lt;/code&gt;, and you’re logged in.&lt;/p&gt;&lt;p&gt;&lt;strong&gt;&lt;em&gt;Note:&lt;/em&gt;&lt;/strong&gt; This opens security issues if others use your computer. Be sure your individual machine is password protected, or skip this step if there’s no way to keep miscreants and ne’er-do-wells off your system.&lt;/p&gt;&lt;p&gt;The basic structure of the config file is simple. It consists of a series of records for each authority file, user, and directory you use to log in:&lt;/p&gt;&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;Host sanity_cms
 HostName jacksonville.dreamhost.com
 User sanity_cms
 IdentityFile ~/.ssh/sanity_cms&lt;/code&gt;&lt;/pre&gt;&lt;p&gt;Here’s what each line does:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;&lt;code&gt;Host&lt;/code&gt; specifies the short name you’ll use to log in with SSH&lt;/li&gt;&lt;li&gt;&lt;code&gt;HostName&lt;/code&gt; specifies the server and domain (remember to change “jacksonville” to your own server)&lt;/li&gt;&lt;li&gt;&lt;code&gt;User&lt;/code&gt; specifies the user for this log-in. In this case, it’s the user we created above.&lt;/li&gt;&lt;li&gt;&lt;code&gt;IdentityFile&lt;/code&gt; specifies the path to that user’s corresponding private key&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;Note the spaces for the three lines under “Host.” This is how SSH knows these directives go together. You’ll create this file in the ~/.ssh directory on your machine. Name the file simply “config”—there is no &lt;em&gt;.type&lt;/em&gt; file extension after it.&lt;/p&gt;&lt;p&gt;A lot of terminal tutorials recommend using &lt;a href=&quot;https://www.vim.org/&quot;&gt;VIM&lt;/a&gt;, a terminal-based text editor, for this kind of thing. You can go this route if you like, but I find it super unintuitive, and see no reason not to use the same text editor I use for everything else to create a simple file. 🤷‍♂️&lt;/p&gt;&lt;p&gt;Since .ssh is a hidden file, you’ll need to un-hide it before you can navigate to it with Mac’s Finder. On the current Mac OS, you can press &lt;code&gt;cmd + shift + .&lt;/code&gt; when you’re in Finder and it will show your hidden files. The .ssh file will be in the Users/YOURUSERNAME/directory. When you open it, you should see the keys we’ve already created. Create a new file in that directory with VS Code, Sublime Text, or whatever editor you use, then add your config record using the parameters above.&lt;/p&gt;&lt;p&gt;Save the file and log in with &lt;code&gt;ssh sanity_cms&lt;/code&gt; (or whatever you’ve named your host):&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/f2df1be13aa2ba75b1e65c06dba3a5759ef23dd4-1300x732.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;676&quot; alt=&quot;Screenshot of a terminal window showing successful DreamHost log in via simple SSH command&quot; /&gt;&lt;/figure&gt;&lt;p&gt;Now revel in the glory of simple password-less log-in! 🎉&lt;/p&gt;&lt;p&gt;(…or hit the “troubleshooting” section below 🧐)&lt;/p&gt;&lt;h2 id=&quot;set-up-a-workflow-on-github-actions&quot;&gt;Set Up a Workflow on GitHub Actions&lt;/h2&gt;&lt;p&gt;GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate your build, test, and deployment pipeline. You can use the shell access and authentication keys we set up in step one to use GitHub Actions to build and push a Sanity Studio instance to your new DreamHost subdomain every time you push to the main branch—all without having to log in or move files around manually.&lt;/p&gt;&lt;p&gt;You can think of a GitHub Actions workflow as a way to “borrow” a new, single use computer, set it up with your development environment, complete a task, then wipe the whole thing clean and give it back. There’s a lot more you can do with GitHub Actions, but this is a good way to get familiar with the basic steps if you’re new to the tool.&lt;/p&gt;&lt;p&gt;The tasks we want to accomplish are to build a new version of Sanity Studio and then upload that version to our studio subdomain. We want this to happen every time we push changes to the main branch of our project repository. Here’s how we’re going to do that:&lt;/p&gt;&lt;ol&gt;&lt;li&gt;Create a workflow file in our public repo&lt;/li&gt;&lt;li&gt;Define the event that triggers the workflow&lt;/li&gt;&lt;li&gt;Set up the development environment&lt;/li&gt;&lt;li&gt;Build the studio&lt;/li&gt;&lt;li&gt;Set up SSH&lt;/li&gt;&lt;li&gt;Upload the studio build to our subdomain&lt;/li&gt;&lt;/ol&gt;&lt;p&gt;This sequence of steps assume that you have a Sanity project that you’re tracking with a public GitHub repository. If you don’t yet have a Sanity project, check out the &lt;a href=&quot;https://www.sanity.io/docs/starters-on-sanity-io-create&quot;&gt;starter projects on the Sanity site&lt;/a&gt;. One of these will have you up and running in minutes. The &lt;a href=&quot;https://www.sanity.io/create?template=sanity-io/sanity-template-gatsby-blog&quot;&gt;Blog with Gatsby&lt;/a&gt; starter is the closest to the setup I’m using for the rest of this guide, but any studio tracked in a GitHub repo should follow similar steps.&lt;/p&gt;&lt;p&gt;&lt;strong&gt;&lt;em&gt;Escape hatch:&lt;/em&gt;&lt;/strong&gt; This workflow has about the same level of complexity (albeit a few more steps) as GitHub’s &lt;a href=&quot;https://docs.github.com/en/actions/quickstart&quot;&gt;quick start&lt;/a&gt; guide for GitHub Actions. If you find yourself a bit overwhelmed, that guide could be an easier way to get your feet wet first. GitHub’s &lt;a href=&quot;https://docs.github.com/en/actions/learn-github-actions&quot;&gt;in-depth tutorial&lt;/a&gt; is also excellent, for when you want to fold a bit more complexity and for greater control over what runs when and how.&lt;/p&gt;&lt;h3 id=&quot;1-create-a-workflow&quot;&gt;1. Create a Workflow&lt;/h3&gt;&lt;p&gt;GitHub Actions workflows are orchestrated via YAML files in the .github/workflows directory. To get started, follow these steps:&lt;/p&gt;&lt;ol&gt;&lt;li&gt;Create a .github/workflows directory in your repository on GitHub&lt;/li&gt;&lt;li&gt;In the .github/workflows directory, create a file named “sanity-studio.yml”&lt;/li&gt;&lt;li&gt;At the top of sanity-studio.yml, give your workflow a name:&lt;/li&gt;&lt;/ol&gt;&lt;pre&gt;&lt;code class=&quot;language-yaml&quot;&gt;name: Build &amp;amp; Deploy Sanity Studio&lt;/code&gt;&lt;/pre&gt;&lt;p&gt;This sanity-studio.yml file defines “the workflow.” &lt;a href=&quot;https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions#workflows&quot;&gt;Workflows&lt;/a&gt; are triggered by &lt;a href=&quot;https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions#events&quot;&gt;Events&lt;/a&gt; and run &lt;a href=&quot;https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions#events&quot;&gt;Jobs&lt;/a&gt; that execute steps in sequential order on a &lt;a href=&quot;https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions#runners&quot;&gt;Runner&lt;/a&gt; (our borrowed computer). A step can be a shell script or an &lt;a href=&quot;https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions#actions&quot;&gt;Action&lt;/a&gt;, which is a bundle of steps for executing a complex and frequently repeated task. You can write your own actions, or you can use &lt;a href=&quot;https://github.com/marketplace?type=actions&quot;&gt;pre-made actions published in GitHub’s Marketplace&lt;/a&gt;. For this workflow, we’re going to use shell scripts and existing actions.&lt;/p&gt;&lt;h3 id=&quot;2-define-the-event-that-triggers-the-workflow&quot;&gt;2. Define the Event that Triggers the Workflow&lt;/h3&gt;&lt;p&gt;Now that we have a workflow defined, we need to tell it when to run by defining the event that triggers it. There are lots of ways to trigger workflows. For our purposes, we want it to run when we push to the main branch.&lt;/p&gt;&lt;p&gt;To do this, we’ll define the &lt;code&gt;on:&lt;/code&gt; key:&lt;/p&gt;&lt;pre&gt;&lt;code class=&quot;language-yaml&quot;&gt;name: Build &amp;amp; Deploy Sanity Studio
on: 
  push: 
    branches:
      - main&lt;/code&gt;&lt;/pre&gt;&lt;p&gt;Be sure to note the indentation—this is important for the structure of your YAML file. Now that we have a trigger, we can begin setting up the job to be run.&lt;/p&gt;&lt;h3 id=&quot;3-set-up-the-development-environment&quot;&gt;3. Set Up the Development Environment&lt;/h3&gt;&lt;p&gt;The Steps in a workflow are executed within one or more Jobs. In this example all of our steps are in a single Job, which we define with the &lt;code&gt;jobs&lt;/code&gt; key:&lt;/p&gt;&lt;pre&gt;&lt;code class=&quot;language-yaml&quot;&gt;name: Build &amp;amp; Deploy Sanity Studio
on: 
  push: 
    branches:
      - main
jobs: 
  build-and-deploy: 
    name: Build &amp;amp; Deploy Sanity Studio 
    runs-on: ubuntu-latest&lt;/code&gt;&lt;/pre&gt;&lt;p&gt;The keys that follow &lt;code&gt;build-and-deploy&lt;/code&gt; configure the job. In this case we want our job to run on the latest version of Linux (this is the most generic option). The &lt;code&gt;name:&lt;/code&gt; key is optional and allows us to give the job a more descriptive name that will be easier to pick out later on the runner.&lt;/p&gt;&lt;p&gt;Once we’ve configured our job, we can start adding steps. We’ll need to install Node and our project dependencies to accomplish our build tasks, but before we do that we’ll check out the repository code. We do this so that any changes that may be pushed while our job is running won’t interfere with the process in progress:&lt;/p&gt;&lt;pre&gt;&lt;code class=&quot;language-yaml&quot;&gt;name: Build &amp;amp; Deploy Sanity Studio
on: 
  push: 
    branches:
      - main
jobs: 
  build-and-deploy: 
    name: Build &amp;amp; Deploy Sanity Studio 
    runs-on: ubuntu-latest
    steps: 
      - name: Checkout Code 
        uses: actions/checkout@v2&lt;/code&gt;&lt;/pre&gt;&lt;p&gt;The Checkout Code step uses the checkout action from GitHub’s “actions” repository, specified with the &lt;code&gt;uses:&lt;/code&gt; key. The @ allows you to specify the version of the repository to use.&lt;/p&gt;&lt;p&gt;Next we’ll install Node. Here we’ll also use an action from the GitHub Actions repository. This action adds the &lt;code&gt;with:&lt;/code&gt; key, which specifies the version of Node to use. “17.x” means the newest release of version 17:&lt;/p&gt;&lt;pre&gt;&lt;code class=&quot;language-yaml&quot;&gt;name: Build &amp;amp; Deploy Sanity Studio
on: 
  push: 
    branches:
      - main
jobs: 
  build-and-deploy: 
    name: Build &amp;amp; Deploy Sanity Studio 
    runs-on: ubuntu-latest
    steps: 
      - name: Checkout Code 
        uses: actions/checkout@v2
      - name: Install Node.js 
        uses: actions/setup-node@v1 
        with: 
          node-version: &apos;17.x&apos;&lt;/code&gt;&lt;/pre&gt;&lt;p&gt;Finally, we install project dependencies with npm, which is now available as we’ve installed Node. Instead of the &lt;code&gt;uses:&lt;/code&gt; key, which specifies an action, here we use the &lt;code&gt;run:&lt;/code&gt; key. This allows us to run command line commands, just as you would do in the terminal. &lt;code&gt;npm ci&lt;/code&gt; will install project dependencies (&lt;code&gt;ci&lt;/code&gt; stands for ‘clean install’ and is the preferred install option for automated environments):&lt;/p&gt;&lt;pre&gt;&lt;code class=&quot;language-yaml&quot;&gt;name: Build &amp;amp; Deploy Sanity Studio
on: 
  push: 
    branches:
      - main
jobs: 
  build-and-deploy: 
    name: Build &amp;amp; Deploy Sanity Studio 
    runs-on: ubuntu-latest
    steps: 
      - name: Checkout Code 
        uses: actions/checkout@v2
      - name: Install Node.js 
        uses: actions/setup-node@v1 
        with: 
          node-version: &apos;17.x&apos; 
      - name: Install Project Dependencies 
        run: npm ci 
        working-directory: studio&lt;/code&gt;&lt;/pre&gt;&lt;p&gt;We’ve also added a &lt;code&gt;working-directory&lt;/code&gt; key in this step. This tells GitHub to execute the run command in the /studio directory. It’s like changing directories in the terminal with &lt;code&gt;cd.&lt;/code&gt; We need to specify a working directory here because this project repo—like Sanity’s Sanity-Gatsby starter—is a &lt;a href=&quot;https://en.wikipedia.org/wiki/Monorepo&quot;&gt;“monorepo”&lt;/a&gt;: it’s got two distinct projects wrapped into one repository. One is for the Gatsby front end, one is for Sanity Studio. We only need to install dependencies for Sanity for this job, so we’ll be working in just that directory.&lt;/p&gt;&lt;h3 id=&quot;4-build-sanity-studio&quot;&gt;4. Build Sanity Studio&lt;/h3&gt;&lt;p&gt;With our dependencies installed, we can now instruct our runner to build a fresh version of Sanity Studio. There are three steps in this task:&lt;/p&gt;&lt;ol&gt;&lt;li&gt;Installing the Sanity Command Line Interface (CLI)&lt;/li&gt;&lt;li&gt;Running the &lt;code&gt;$ sanity build&lt;/code&gt; command&lt;/li&gt;&lt;li&gt;Verifying the build&lt;/li&gt;&lt;/ol&gt;&lt;p&gt;&lt;strong&gt;&lt;em&gt;OMG-this-guide-is-getting-long note:&lt;/em&gt;&lt;/strong&gt; In order to keep the workflow code block manageable, I’ll focus on just these steps for now, but don’t worry—I’ll put the whole thing together in a copy-able block below when it’s complete.&lt;/p&gt;&lt;p&gt;First we’ll install the Sanity CLI. We can do this in GitHub actions with a simple NPM install command and the &lt;code&gt;run&lt;/code&gt; key. There is a published &lt;a href=&quot;https://github.com/sanity-io/github-action-sanity&quot;&gt;GitHub Action for Sanity&lt;/a&gt; available, but since we’re only going to be running the build command, which doesn’t require an authorization token, I’ve found that simply installing the CLI is faster:&lt;/p&gt;&lt;pre&gt;&lt;code class=&quot;language-yaml&quot;&gt;      ... 
      - name: Install Sanity CLI 
        run: npm install -g @sanity/cli&lt;/code&gt;&lt;/pre&gt;&lt;p&gt;Once the CLI is installed, we’ll run &lt;code&gt;sanity build&lt;/code&gt; to build the production version of the Studio. As we did with project dependencies above, we want this command to run as if we had &lt;code&gt;cd&lt;/code&gt;‘d into the studio folder, so we’ll use the &lt;code&gt;working-directory:&lt;/code&gt; key:&lt;/p&gt;&lt;pre&gt;&lt;code class=&quot;language-yaml&quot;&gt;      ... 
      - name: Install Sanity CLI 
        run: npm install -g @sanity/cli
      - name: Build Studio 
        run: sanity build 
        working-directory: studio&lt;/code&gt;&lt;/pre&gt;&lt;p&gt;The last action in this section is a check to make sure the build ran as we expected:&lt;/p&gt;&lt;pre&gt;&lt;code class=&quot;language-yaml&quot;&gt;      ... 
      - name: Install Sanity CLI 
        run: npm install -g @sanity/cli
      - name: Build Studio 
        run: sanity build 
        working-directory: studio
      - name: Verify Build 
        run: ls -la dist 
        working-directory: studio&lt;/code&gt;&lt;/pre&gt;&lt;p&gt;&lt;code&gt;ls&lt;/code&gt; lists the contents of the /dist directory, specified after the command&lt;/p&gt;&lt;ul&gt;&lt;li&gt;The &lt;code&gt;-la&lt;/code&gt; option is two commands combined into one that give us a full reading of the output: it combines the options for long list format, &lt;code&gt;-l&lt;/code&gt;, and for show all files, &lt;code&gt;-a&lt;/code&gt;&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;This list will show up in GitHub actions when you run it. I find these kinds of checks useful for building an effective set of commands one step at a time. This usually means I end up spending less time debugging—and gives me some checkpoints when I do have to work out a problem. That said, once you’re sure everything is working, you can safely remove this step from the workflow.&lt;/p&gt;&lt;h3 id=&quot;5-set-up-ssh&quot;&gt;5. Set Up SSH&lt;/h3&gt;&lt;p&gt;Next we’ll use the SSH keys we created in the first part of this guide to allow our action to access our DreamHost server. This will let us push the Sanity Studio instance we just built to our new subdomain’s web directory.&lt;/p&gt;&lt;p&gt;To do this, you need to make the private key from the RSA pair you created earlier available to the GitHub Actions runner. You don’t want to just add that key directly into a step, however, because that means that anyone looking at your repo would be able to copy and use your key. If your repo is public, this is basically giving the entire internet access to your server. 🧐&lt;/p&gt;&lt;p&gt;Fortunately, GitHub has a tool for keeping your secrets, well, secret. It’s called “Secrets,” and you can get to it from the “Settings” tab in your repository.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/1d672581699684f4560436e58fc2ad3918072ead-1300x790.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;729&quot; alt=&quot;Screenshot of the GitHub Actions secrets panel showing a security-obscured list of repository secrets&quot; /&gt;&lt;/figure&gt;&lt;p&gt;To use your private RSA key in our SSH action:&lt;/p&gt;&lt;ol&gt;&lt;li&gt;Click the “Add a new repository secret” button&lt;/li&gt;&lt;li&gt;Copy the contents of your private named key file into the Value field. Your private key will begin and end with the these statements:&lt;br/&gt;&lt;code&gt;-----BEGIN OPENSSH PRIVATE KEY-----&lt;/code&gt;&lt;br/&gt;and&lt;br/&gt;&lt;code&gt;​​-----END OPENSSH PRIVATE KEY-----&lt;/code&gt;&lt;br/&gt;Copy everything between—and including—these lines.&lt;/li&gt;&lt;li&gt;Give your secret a name. I’ve used SANITY_CMS_DREAMHOST_SSH_KEY in this example. All caps and “snake case” (underscores) is the naming convention for secure keys.&lt;/li&gt;&lt;/ol&gt;&lt;p&gt;Now that you have a secure way to access your RSA key, we can use it to set up the SSH permission step in our workflow:&lt;/p&gt;&lt;pre&gt;&lt;code class=&quot;language-yaml&quot;&gt;      ...
      - name: Set Up SSH
        run: |
          mkdir -p ~/.ssh/
          echo &quot;${{ secrets.SANITY_CMS_DREAMHOST_SSH_KEY }}&quot; &amp;gt; ~/.ssh/sanity_cms
          sudo chmod 600 ~/.ssh/sanity_cms
          ssh-keyscan -H &quot;jacksonville.dreamhost.com&quot; &amp;gt; ~/.ssh/known_hosts&lt;/code&gt;&lt;/pre&gt;&lt;p&gt;There’s a lot going on in this step. Here’s the breakdown:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;The pipe symbol at the the &lt;code&gt;run:&lt;/code&gt; key signifies that the indented text that follows should be interpreted as a multi-line value. You can think of this step as actually four steps you would otherwise run on the command line in sequence.&lt;/li&gt;&lt;li&gt;&lt;code&gt;mkdir -p ~/.ssh/&lt;/code&gt; creates an .ssh directory at the root of our runner (the GitHub Action computer we’re “borrowing” for this workflow). The &lt;code&gt;-p&lt;/code&gt; option creates any needed parent directories.&lt;/li&gt;&lt;li&gt;&lt;code&gt;echo &amp;quot;${{ secrets.SANITY_CMS_DREAMHOST_SSH_KEY }}&amp;quot;&lt;/code&gt; outputs the content of our secure private key using the &lt;a href=&quot;https://docs.github.com/en/actions/security-guides/encrypted-secrets#using-encrypted-secrets-in-a-workflow&quot;&gt;“Secrets Context”&lt;/a&gt;. You can read more about &lt;a href=&quot;https://docs.github.com/en/actions/learn-github-actions/contexts&quot;&gt;Contexts&lt;/a&gt; and &lt;a href=&quot;https://docs.github.com/en/actions/learn-github-actions/expressions&quot;&gt;Expression Syntax&lt;/a&gt; (&lt;code&gt;${{ &amp;lt;expression&amp;gt; }}&lt;/code&gt;) in the GitHub Actions docs.&lt;/li&gt;&lt;li&gt;&lt;code&gt;~/.ssh/sanity_cms&lt;/code&gt; adds that secret to the file &lt;code&gt;sanity_cms&lt;/code&gt; in the .ssh directory we just created&lt;/li&gt;&lt;li&gt;&lt;code&gt;sudo chmod 600 ~/.ssh/sanity_cms&lt;/code&gt; limits access to your key to just you. GitHub actions require this for security.&lt;/li&gt;&lt;li&gt;The last line, &lt;code&gt;ssh-keyscan -H ...&lt;/code&gt; adds a &lt;a href=&quot;https://linux.die.net/man/1/ssh-keygen&quot;&gt;hash of our host address&lt;/a&gt; to the .ssh directory in the &lt;code&gt;known_hosts&lt;/code&gt; file. “known_hosts” is a list of all SSH server host public keys that you have determined are accurate. &lt;a href=&quot;https://www.techrepublic.com/article/the-4-most-important-files-for-ssh-connections/&quot;&gt;Read more about known-host files here&lt;/a&gt;.&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;This step is heavily indebted to Andrew Villazon’s excellent &lt;a href=&quot;https://www.andrewvillazon.com/automatically-deploying-with-github-actions/&quot;&gt;“Automatically deploying a Gatsby site with Github Actions”&lt;/a&gt; article. Check it out if you’re a Gatsby user!&lt;/p&gt;&lt;h3 id=&quot;6-upload-the-studio-build-to-the-subdomain&quot;&gt;6. Upload the Studio Build to the Subdomain&lt;/h3&gt;&lt;p&gt;Now that we have a) a distribution-ready build of Sanity Studio, and b) SSH access, we can finally instruct the workflow to upload that build to the subdomain we created in the very first task above:&lt;/p&gt;&lt;pre&gt;&lt;code class=&quot;language-yaml&quot;&gt;      ...
      - name: SFTP Upload
        run: sftp -i ~/.ssh/SANITY_CMS SANITY_CMS@JACKSONVILLE.dreamhost.com &amp;lt;&amp;lt;&amp;lt; $&apos;cd studio.uxmethods.org \n put -r studio/dist/*&apos;&lt;/code&gt;&lt;/pre&gt;&lt;p&gt;Here’s a breakdown of what’s going on in that &lt;code&gt;run:&lt;/code&gt; key:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;&lt;code&gt;sftp -i ~/.ssh/...&lt;/code&gt; opens a connection to our server using SSH File Transfer Protocol (sftp) using the identify file (&lt;code&gt;-i&lt;/code&gt;) we created earlier and loaded into the &lt;code&gt;~/.ssh&lt;/code&gt; directory in our runner (our borrowed computer)&lt;/li&gt;&lt;li&gt;&lt;code&gt;&amp;lt;&amp;lt;&amp;lt;&lt;/code&gt; is a “here-string”: it passes the quoted text on the right of the here-string to the standard input of the command on the left. You can think of this as running a sequence of commands from the SFTP prompt (credit for this formulation and clear explanation again goes to &lt;a href=&quot;https://www.andrewvillazon.com/automatically-deploying-with-github-actions/&quot;&gt;Andrew Villazon&lt;/a&gt;).&lt;/li&gt;&lt;li&gt;&lt;code&gt;cd studio.uxmethods.org&lt;/code&gt; moves us into our subdomain’s directory on the DreamHost server&lt;/li&gt;&lt;li&gt;&lt;code&gt;\n put -r studio/dist/*&lt;/code&gt; creates a line break (&lt;code&gt;\n&lt;/code&gt;), which distinguishes our second command, then runs a &lt;code&gt;put&lt;/code&gt; command which uploads the files in the &lt;code&gt;studio/dist/&lt;/code&gt; directory on our runner to the subdomain directory on the server. The &lt;a href=&quot;https://man.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man1/sftp.1?query=sftp&amp;amp;sec=1&quot;&gt;recursive option&lt;/a&gt; (&lt;code&gt;-r&lt;/code&gt;) makes sure that subdirectories are included.&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;And that’s it! Here’s the entire workflow:&lt;/p&gt;&lt;pre&gt;&lt;code class=&quot;language-yaml&quot;&gt;name: Build &amp;amp; Deploy Sanity Studio
on: 
  push: 
    branches:
      - main
jobs: 
  build-and-deploy: 
    name: Build &amp;amp; Deploy Sanity Studio 
    runs-on: ubuntu-latest
    steps: 
      - name: Checkout Code 
        uses: actions/checkout@v2
      - name: Install Node.js 
        uses: actions/setup-node@v1 
        with: 
          node-version: &apos;17.x&apos; 
      - name: Install Project Dependencies 
        run: npm ci 
        working-directory: studio
      - name: Install Sanity CLI
        run: npm install -g @sanity/cli
      - name: Build Studio
        run: sanity build
        working-directory: studio
      - name: Verify Build
        run: ls -la dist
        working-directory: studio
      - name: Set Up SSH
        run: |
          mkdir -p ~/.ssh/
          echo &quot;${{ secrets.SANITY_CMS_DREAMHOST_SSH_KEY }}&quot; &amp;gt; ~/.ssh/sanity_cms
          sudo chmod 600 ~/.ssh/sanity_cms
          ssh-keyscan -H &quot;jacksonville.dreamhost.com&quot; &amp;gt; ~/.ssh/known_hosts
      - name: SFTP Upload
        run: sftp -i ~/.ssh/SANITY_CMS SANITY_CMS@JACKSONVILLE.dreamhost.com &amp;lt;&amp;lt;&amp;lt; $&apos;cd studio.uxmethods.org \n put -r studio/dist/*&apos;&lt;/code&gt;&lt;/pre&gt;&lt;p&gt;Push the workflow file to your main GitHub branch, then head over to your repository page and click on the “Actions” tab. You should see your workflow running in the “All workflows” lists:&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/84dcf41df947faf3fd2ef013320bc1e565fe8347-1300x790.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;729&quot; alt=&quot;Screenshot of the Build and Deploy workflow in the process of being run in GitHub Actions&quot; /&gt;&lt;/figure&gt;&lt;p&gt;Click into the workflow in progress, and then into the currently running job and you’ll see the steps we wrote out above being executed. You can click into individual steps and see the commands being run. This is also where you can check in on the output of the verification steps we set up along the way.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/a687526f3e339eeea76a999f13dafe8a3074eb9b-1300x790.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;729&quot; alt=&quot;Screenshot of the Build &amp;amp; Deploy workflow showing details of the run in progress&quot; /&gt;&lt;/figure&gt;&lt;p&gt;If any of your steps fail, this is where you’ll find error messages. If you’ve verified that your SSH setup works and have followed along with the intermediary verification steps in the workflow, you should be able to spot any bugs by reading the error messages. (Check out the “troubleshooting” section below for tips on common problems.)&lt;/p&gt;&lt;p&gt;Once your workflow completes successfully, you’ll see a green check next to the task, job, and workflow on each of the corresponding pages. If you go to your subdomain, you should see something that looks like this:&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/0e791a697921e271ba26c8422a6e600930e41a96-1300x790.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;729&quot; alt=&quot;Screenshot showing the error message users will see if Sanity Studio is hosted, but not yet authorized&quot; /&gt;&lt;/figure&gt;&lt;p&gt;This &lt;em&gt;looks&lt;/em&gt; like something went wrong, but it’s exactly what we want here. This means that Sanity Studio was successfully uploaded to your subdomain.&lt;/p&gt;&lt;p&gt;It also means that Sanity’s built-in security is working: until you explicitly allow this origin (your subdomain) to access your Sanity dataset, there’s no way that you (or anyone pretending to be you) can read, write, or otherwise fiddle with your content via Sanity Studio. This brings us to our final step.&lt;/p&gt;&lt;h2 id=&quot;add-permissions-to-sanity&quot;&gt;Add Permissions to Sanity&lt;/h2&gt;&lt;p&gt;In order to allow your installed Sanity Studio instance to access your Sanity content dataset, you need to allow your new Studio subdomain as a CORS origin. CORS (&lt;a href=&quot;https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS&quot;&gt;Cross-Origin Resource Sharing&lt;/a&gt;) rules control which domains can access a resource. To add your Studio subdomain, log in to your Sanity admin account and navigate to the “CORS origin” menu in the “API” tab.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/ae360c733f4d1f19170504afb7cb8173789f68ca-1300x790.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;729&quot; alt=&quot;Sanity Admin CORS origins administration panel showing security-obscured authorized origins and the add origin button&quot; /&gt;&lt;/figure&gt;&lt;p&gt;Click the “Add CORS Origin” button, then add the full URL of your studio subdomain in the “origin” field. Be sure to click the “allow credentials” box so that you can log in with your username and password:&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/e7d2b9e08192a8c0cd03d7927849a6934ddca8bb-1300x790.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;729&quot; alt=&quot;Screenshot of details for adding a new CORS origin to Sanity&quot; /&gt;&lt;/figure&gt;&lt;p&gt;Now when you visit your Studio Subdomain and enter your Sanity username and password, you’ll find your self-hosted Sanity Studio up and running and waiting for new content.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/1ad70179c2d541e5f1d028d3cc3a7636ddad8d22-1300x790.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;729&quot; alt=&quot;A Sanity Studio instance running on a custom subdomain&quot; /&gt;&lt;/figure&gt;&lt;h2 id=&quot;additional-use-cases&quot;&gt;Additional Use Cases&lt;/h2&gt;&lt;p&gt;As you’ve no doubt picked up on by this point, self-hosting a Sanity Studio with continuous deployment via GitHub Actions involves a bunch of little steps—and, if your experience is like mine, usually at least some troubleshooting along the way. I really am sorry about the length of this guide, but if you’ve gotten this far I hope you’ve also realized that none of these steps are “magic” or beyond the grasp of someone with some fundamental computer skills and a healthy dose of determination.&lt;/p&gt;&lt;p&gt;Fortunately, once you get comfortable with the concepts and basic steps described here, there are a lot of other ways to use SSH and GitHub Actions to self-publish and automate parts of your workflow. For UX Methods, for instance, I use workflows to:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;Publish Sanity Studio (as shown here)&lt;/li&gt;&lt;li&gt;Build and deploy the UX Methods production site&lt;/li&gt;&lt;li&gt;Build a UX Methods staging site to iterate and experiment with new ideas&lt;/li&gt;&lt;li&gt;Transform Sanity content into RDF triples and load them into a knowledge graph, which is used to create &lt;a href=&quot;https://data.world/andyfitzgerald/ux-methods/workspace/intro&quot;&gt;recommendations and navigation for UX Methods.&lt;/a&gt;&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;GitHub’s &lt;a href=&quot;https://github.com/marketplace?type=actions&quot;&gt;Actions Marketplace&lt;/a&gt; also has &lt;em&gt;thousands&lt;/em&gt; of pre-built actions you can use and combine in jobs and workflows, and this list is growing all the time. Once you have the basics of how Actions work down, the possibility of what you might do with them is large indeed.&lt;/p&gt;&lt;p&gt;I hope this guide has helped you get a sense of how to use GitHub Actions to simplify your Sanity workflow—and has helped you build something useful in the process. If you run into any snags in the steps above, do check out the troubleshooting tips below. If something continues to befuddle you, or just won’t work, please let me know either in a comment or via email. I’ll respond where (and when) I can, and will update the troubleshooting guide with any tips others might find useful as well.&lt;/p&gt;&lt;h2 id=&quot;troubleshooting&quot;&gt;Troubleshooting&lt;/h2&gt;&lt;h3 id=&quot;ssh-problems&quot;&gt;SSH Problems&lt;/h3&gt;&lt;p&gt;Before you try to automate log-in, make sure you can log in with your password first:&lt;/p&gt;&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;$ ssh YOUR_USER@SERVER.dreamhost.com $ YOUR_PASSWORD&lt;/code&gt;&lt;/pre&gt;&lt;p&gt;If you can log in locally, your problem may be with permissions or passwords:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;Make sure you’ve added shell access&lt;/li&gt;&lt;li&gt;Give the server time to propagate changes&lt;/li&gt;&lt;li&gt;Reset your password if it’s not working (this one fixes &lt;em&gt;a lot&lt;/em&gt; of log-in problems)&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;If you’re having problems with your RSA keys:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;Make sure you’ve added your public key to the DreamHost server, and that you’re using your private key to log in&lt;/li&gt;&lt;li&gt;Be sure you’re using your user name and your server name (not my placeholders)&lt;/li&gt;&lt;/ul&gt;&lt;h3 id=&quot;github-actions-problems&quot;&gt;GitHub Actions Problems&lt;/h3&gt;&lt;p&gt;Andrew Villazon gives some &lt;a href=&quot;https://www.andrewvillazon.com/automatically-deploying-with-github-actions/&quot;&gt;examples of how to use Secrets for your username and host name&lt;/a&gt;, in addition to using them for your public RSA key. I’ve omitted this extra level of security for the demos in this guide, but for production work, I recommend obscuring anything that might be used to gain unauthorized access to your repository and workflow.&lt;/p&gt;&lt;h3 id=&quot;sanity-problems&quot;&gt;Sanity Problems&lt;/h3&gt;&lt;p&gt;Since Sanity Studio is a Single Page App (SPA), trying to navigate to any page (other than the index page) directly may lead to 404 errors unless your server supports SPAs already. You can correct this by adding an entry to the .htaccess file in your web directory. You can find some &lt;a href=&quot;https://gist.github.com/davemackintosh/8ac35fff747dbf2c95e1&quot;&gt;examples of working configurations here&lt;/a&gt;. (I use the first example shown on UX Methods and it works fine.)&lt;/p&gt;</content>
  </entry>
  <entry>
    <title type="text">How to Choose Topics for Card Sorting</title>
    <link rel="alternate" type="text/html" href="https://preview.andyfitzgeraldconsulting.com/insights/choosing-card-sorting-topics/"/>
    <id>https://preview.andyfitzgeraldconsulting.com/insights/choosing-card-sorting-topics/</id>
    <published>2020-09-17T00:00:00Z</published>
    <updated>2020-09-17T00:00:00Z</updated>
    <summary type="text">Improve the quality of your card sorting results with client collaboration.</summary>
    <category term="Method"/>
    <category term="Content Analysis"/>
    <category term="Mental Models"/>
    <content type="html">&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/80eae8653ffc76e700628999cc24f6a8567e5786-1300x500.jpg?rect=206,0,888,500&amp;amp;w=888&amp;amp;h=500&amp;amp;fit=crop&amp;amp;auto=format&quot; width=&quot;888&quot; height=&quot;500&quot; alt=&quot;Close up of a finger pointing to a card among other cards on a table. &quot; /&gt;&lt;/figure&gt;&lt;p&gt;Like many “so easy anyone can do it processes,” there is a pitfall in setting up and running an effective card sorting exercise: selecting the right topics for cards. With a little bit of preparation, teamwork, and in-person (or virtual) facilitation, it’s possible to fine tune your card sorting exercise set-up process to substantially improve both the quality of your results, and the depth of insight those results reveal.&lt;/p&gt;&lt;p&gt;Card sorting is perhaps one of the most effective tools we have for understanding our users’ ideas about how a particular set of content should be organized. It’s lightweight, quick, inexpensive, and can add value at multiple places in the project lifecycle.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/066c57b8a7ae3ad5e2f932afeaa659a48fca15c0-977x720.gif?w=977&amp;amp;auto=format&quot; width=&quot;977&quot; height=&quot;720&quot; alt=&quot;A example card sort in Optimal Workshop to illustrate the basic technique.&quot; /&gt;&lt;figcaption&gt;A example sort in Optimal Workshop illustrating card sorting basics.&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;Like many “so easy anyone can do it” processes, however, there is a pitfall in setting up and running an effective card sorting exercise which, if not negotiated carefully, can leave everyone wondering where the promised insight is: selecting the right topics for cards.&lt;/p&gt;&lt;p&gt;In this article, I’ll share a process for getting not only the right number and kinds of cards (ideally 30 to 60, at the same level of granularity), but also for selecting the right terms for the purposes of a particular study within a particular organization. With a little bit of preparation, teamwork, and in-person (or virtual) facilitation, it’s possible to fine tune your set-up process to substantially improve both the quality of your results, and the depth of insight those results reveal.&lt;/p&gt;&lt;h2 id=&quot;choosing-topics-collaboratively&quot;&gt;Choosing Topics Collaboratively&lt;/h2&gt;&lt;p&gt;Reducing and refining the list of “all possible card sorting terms” down to the 50 or so that will be tested is often framed as a “just figure it out” activity. Sometimes it’s left up to the individual UX researcher or designer. Sometimes it’s dictated to teams by clients. Often it’s some combination of the two. Without a clear sense of goals and shared purpose, any of these options leave a lot of team wisdom on the table.&lt;/p&gt;&lt;p&gt;An alternative approach for getting a useful and well targeted selection of cards for a given card sorting study is to make the selection process a planned, collaborative exercise. This gives you a structured, repeatable method for choosing card topics that meet project goals.&lt;/p&gt;&lt;p&gt;After having run these sessions for a couple years, I’ve also discovered some additional benefits to making the term selection process a team sport:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;It brings the multiple points of view into the mix&lt;/li&gt;&lt;li&gt;It surfaces additional insight about the subject area, content, and stakeholders&lt;/li&gt;&lt;li&gt;It helps generate buy-in from project team members and clients&lt;/li&gt;&lt;li&gt;It usually turns out to be a fun activity—and in any case is way less stressful than trying to come up with a good term list on your own&lt;/li&gt;&lt;/ul&gt;&lt;h2 id=&quot;running-the-exercise&quot;&gt;Running the Exercise&lt;/h2&gt;&lt;p&gt;To get the most out of your session, you’ll want to recruit participants from your project team, subject matter experts in your client’s organization, and stakeholders with knowledge of the project and an investment in its outcome. A handful of folks is usually enough to generate an insightful list.&lt;/p&gt;&lt;p&gt;The exercise itself takes 2 to 3 hours, depending on the number of participants. I use &lt;a href=&quot;https://www.google.com/sheets/about/&quot;&gt;Google Sheets&lt;/a&gt; and &lt;a href=&quot;https://miro.com/&quot;&gt;Miro&lt;/a&gt; for both in-person and online versions of these sessions, as I’ll show in the examples below, so remote facilitation is built in. If you’re facilitating remotely, you’ll also want to arrange for conferencing software with reliable video collaboration tools.&lt;/p&gt;&lt;p&gt;Once you’ve got your tools in place, the overall process looks like this:&lt;/p&gt;&lt;ol&gt;&lt;li&gt;Identify and prioritize card sort study goals&lt;/li&gt;&lt;li&gt;Collect concepts&lt;/li&gt;&lt;li&gt;Groom collected concepts&lt;/li&gt;&lt;li&gt;Refine labels&lt;/li&gt;&lt;li&gt;Test and validate candidate cards&lt;/li&gt;&lt;/ol&gt;&lt;p&gt;I’ve illustrated each of these steps in detail below, with examples drawn from a recent collaboration session I conducted with a client in higher education. I’ve also shared an &lt;a href=&quot;https://docs.google.com/document/d/1rIi9WbTSUoEn-2HPjCIVz_ZmWZ_YJvKF7Wp--qhRsZI/edit?usp=sharing&quot;&gt;agenda starter template on Google Docs&lt;/a&gt;, which you should feel free to copy and adapt to your own project needs.&lt;/p&gt;&lt;h3 id=&quot;1-identify-and-prioritize-card-sort-study-goals&quot;&gt;1. Identify and Prioritize Card Sort Study Goals&lt;/h3&gt;&lt;p&gt;&lt;em&gt;Goal: Make sure you know what you want to accomplish before you start collecting concepts.&lt;/em&gt;&lt;/p&gt;&lt;p&gt;Your study goals should go beyond “how do participants sort our content?” Try to put your finger on what you need to know about this particular collection of content—and how your target users think about it—in order to make effective design decisions.&lt;/p&gt;&lt;p&gt;For my recent higher ed client, we came up with four college-specific goals for our study:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;Learn how participants think about distinct audiences&lt;/li&gt;&lt;li&gt;Learn about how participants categorize content for distinct audiences&lt;/li&gt;&lt;li&gt;Learn how participants group resources that are time based, action oriented, and evergreen&lt;/li&gt;&lt;li&gt;Learn what resources participants deem essential to their success at the college&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;This last goal was a “stretch goal”: there was a good chance we wouldn’t be able to answer it with the card sort alone, but card sort data taken together with comments and questionnaire responses would allow us to gain some insight into it.&lt;/p&gt;&lt;p&gt;&lt;em&gt;For a tutorial on extracting keywords from free form comments, check out “&lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/insights/keyword-extraction-nlp/&quot;&gt;A Beginner’s Guide to Keyword Extraction with Natural Language Processing&lt;/a&gt;.”&lt;/em&gt;&lt;/p&gt;&lt;h3 id=&quot;2-collect-concepts&quot;&gt;2. Collect Concepts &lt;/h3&gt;&lt;p&gt;&lt;em&gt;Goal: Get all the possible concepts that might help inform your study goals out on the (virtual) table.&lt;/em&gt;&lt;/p&gt;&lt;p&gt;Brainstorm and record all the possible card sort concepts that could be included to generate the insight needed to meet the goals you’ve identified. Possible sources for inspiration might include:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;existing website(s)&lt;/li&gt;&lt;li&gt;sitemaps &amp;amp; org charts&lt;/li&gt;&lt;li&gt;content inventories&lt;/li&gt;&lt;li&gt;stakeholder input&lt;/li&gt;&lt;li&gt;user goals and needs research&lt;/li&gt;&lt;li&gt;survey output&lt;/li&gt;&lt;li&gt;competitive analysis research&lt;/li&gt;&lt;li&gt;third party industry research&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;For this part of the activity, split your sources up among participants. Appoint a scribe and have participants shout out possible concepts, or have them make lists and combine them once everyone is finished. I recommend recording everything in a spreadsheet so you can easily move the data to sticky notes later. This is a generative activity, so don’t hold back—you’ll cull this word herd in the next step.&lt;/p&gt;&lt;p&gt;Once you’ve extracted possible card content from your sources, send your participants on a break and deduplicate and normalize what you’ve gathered. If you find terms that are clearly variants, pick one and eliminate the other. If there’s any question they might not mean the same thing, though, leave them: you don’t want to eliminate terms that could be conceptually distinct without team input.&lt;/p&gt;&lt;p&gt;You should end up with a list of anywhere from 80 to a couple hundred concepts. Here are the first 20 of the 97 terms we generated in my higher ed client’s session:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;Academic calendar&lt;/li&gt;&lt;li&gt;Academic departments&lt;/li&gt;&lt;li&gt;Academic progress&lt;/li&gt;&lt;li&gt;Academic standards&lt;/li&gt;&lt;li&gt;Advising&lt;/li&gt;&lt;li&gt;Alumni&lt;/li&gt;&lt;li&gt;Athletics&lt;/li&gt;&lt;li&gt;Biology Learning Center&lt;/li&gt;&lt;li&gt;Bookstore&lt;/li&gt;&lt;li&gt;Browse all degrees &amp;amp; certificates&lt;/li&gt;&lt;li&gt;Cafeteria and Food services&lt;/li&gt;&lt;li&gt;Calendar of Events&lt;/li&gt;&lt;li&gt;Campus maps&lt;/li&gt;&lt;li&gt;Career services&lt;/li&gt;&lt;li&gt;class schedule&lt;/li&gt;&lt;li&gt;Clubs &amp;amp; Organizations&lt;/li&gt;&lt;li&gt;Co-op preschool&lt;/li&gt;&lt;li&gt;college readiness and ESL&lt;/li&gt;&lt;li&gt;Communication preferences&lt;/li&gt;&lt;li&gt;Community Standard&lt;/li&gt;&lt;/ul&gt;&lt;h3 id=&quot;3-groom-selected-concepts&quot;&gt;3. Groom Selected Concepts&lt;/h3&gt;&lt;p&gt;&lt;em&gt;Goal: Narrow your list of possible topics down to the 30 to 60 right topics for your study goals.&lt;/em&gt;&lt;/p&gt;&lt;p&gt;Once everyone’s back, it’s time to narrow that list of possible concepts down to a list of the right ones, given the goals you’ve identified. For this exercise, drop your list of deduplicated concepts into Miro to create a giant grid.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/79d3044dd379c0dbe75b460072f21145f9b3b276-1280x720.gif?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;675&quot; alt=&quot;Spreadsheet terms being imported into Miro.&quot; /&gt;&lt;figcaption&gt;You can paste your candidate terms directly into Miro to make them into &amp;quot;sticky notes.&amp;quot;&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;If I’m working with a group in person, I put this on a large screen. If we’re collaborating, I have participants open Miro on their end so that we can all actively participate. To get started, grab a “sticky note” and ask the group if it represents a concept you need to gain insight about in order to answer your research questions. If it’s not, move it outside of the frame. If it is, keep it in the frame and move on to the next one.&lt;/p&gt;&lt;p&gt;Once you have a half dozen or so concepts, start asking if they’re all also of the same level of granularity. If you’re starting to collect both parent and child categories, such as “financial aid” and “grants,” “scholarships,” and “loans,” pick the level of granularity that most closely aligns with your study goals and set the concepts at different levels aside. Keep going until you’ve narrowed your set down to 30 to 50 concepts.&lt;/p&gt;&lt;h3 id=&quot;4-refine-labels&quot;&gt;4. Refine Labels&lt;/h3&gt;&lt;p&gt;&lt;em&gt;Goal: Eliminate patterns in labels that will tempt participants to group cards based on similar words, regardless of the concepts they represent.&lt;/em&gt;&lt;/p&gt;&lt;p&gt;Once you have a set of 30 to 50 concepts, ensure that there aren’t any unintended patterns in the labels that will cause users to group them together primarily based on the way they are phrased. This can happen when labels contain recurring words or repeating structures.&lt;/p&gt;&lt;p&gt;With my higher ed client, for instance, we ended up with these three concepts:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;Student accessibility services&lt;/li&gt;&lt;li&gt;Student equity&lt;/li&gt;&lt;li&gt;Student government&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;A hasty participant might be tempted to put all these cards together because they start with “Student,” ignoring the meaning of the concept we’re interested in learning about. To avoid this, we decided that “Diversity and equity” represents the college’s concept of “Student equity” equally well. We also decided that “Accessibility services” didn’t need “Student” in front of it to be clear .&lt;/p&gt;&lt;p&gt;Be sure to discuss and vet these choices with your collaboration team. This is one of the places you’re likely to learn more about the organization, its content, and its users, so be prepared to take notes!&lt;/p&gt;&lt;h3 id=&quot;5-test-and-validate-candidate-cards&quot;&gt;5. Test and Validate Candidate Cards&lt;/h3&gt;&lt;p&gt;&lt;em&gt;Goal: Verify that your final cards can be grouped and that they respond to the goals of your study.&lt;/em&gt;&lt;/p&gt;&lt;p&gt;Now that you have a manageable list of clearly labeled cards, test them out to make sure they can all be grouped with something else and that there is sufficient variety in the concepts to meet the goals of your test.&lt;/p&gt;&lt;p&gt;To do this, duplicate the groomed set of terms and create a copy in Miro for each member of your collaboration group. Then take 10 minutes and have each member of the group sort the cards individually, in their own frame in Miro.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/4f83fa14f5562884243b733ce7a25949e83aa9a9-1300x714.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;659&quot; alt=&quot;Test sorts in Miro from the higher ed project term selection workshop.&quot; /&gt;&lt;figcaption&gt;Test sorts in Miro from the higher ed project term selection workshop.&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;As you go, have everyone take note of cards that:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;were difficult to sort&lt;/li&gt;&lt;li&gt;seemed to have no place&lt;/li&gt;&lt;li&gt;seemed to duplicate other cards in context&lt;/li&gt;&lt;li&gt;were at a different level of granularity than other cards in context&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;After everyone has finished, compare your sorted cards and notes. You should see variety in the way even a small test group organizes content—this is a good sign that our actual test will produce insightful results. If the differences between sorts are from a misunderstanding or conflicting understandings of the concept the card represents, consider revising that card. If differences come from an alternate point of view of how correctly understood concepts could be sorted, you’re on the right track.&lt;/p&gt;&lt;p&gt;This is also where you can check to make sure all your cards can be grouped. If there are any terms that everyone has a hard time placing, check their labels for clarity and ensure they’re at the same level of granularity as the other cards.&lt;/p&gt;&lt;p&gt;With my higher ed client, for example, none of us really knew how to group “Summer camps.” Since summer camps are for children of students and faculty, we rephrased “Summer camps” to “Youth summer camps.” This was clearer in context, and also aligned nicely with our goal of “learning about how participants categorize content for distinct audiences.” To our surprise, participants consistently grouped this card in a way none of us had expected—which gave us insight into our participants’ mental models we likely wouldn’t have had if the label had remained vague.&lt;/p&gt;&lt;h2 id=&quot;conclusion&quot;&gt;Conclusion&lt;/h2&gt;&lt;p&gt;At the end of your collaboration session, you should end up with a set of card sorting topics fine-tuned to your study goals, and labeled to produce relevant insight. You’ll also have a card set that includes the insight of your project and client collaborators and stakeholders, and has been vetted by session participants.&lt;/p&gt;&lt;p&gt;In my experience, this process has been far more reliable—and far less stressful— than “just figuring it out.” Once you factor in the review and revision steps of muscling through card selection on your own, you’ll likely also find that it takes about the same amount of time (if not less).&lt;/p&gt;&lt;p&gt;Perhaps the best part of this approach, though, is that it brings your client along in the topic selection process. After we wrapped up the session I’ve been using as an example here, my client at the college sent me this note (used with permission):&lt;/p&gt;&lt;blockquote&gt;“Getting that work done relieved so much of my stress. To me, this is the hardest task to get right when working on such a complicated system—but one of the most important.”&lt;/blockquote&gt;&lt;p&gt;To get started using this process on your own projects, grab the &lt;a href=&quot;https://docs.google.com/document/d/1rIi9WbTSUoEn-2HPjCIVz_ZmWZ_YJvKF7Wp--qhRsZI/edit?usp=sharing&quot;&gt;agenda starter template from Google Docs&lt;/a&gt;. If getting some hands-on, collaborative help with your own design research and information architecture is more your style, do &lt;a href=&quot;https://preview.andyfitzgeraldconsulting.com/contact/&quot;&gt;drop me a note&lt;/a&gt;—I’d love to hear from you!&lt;/p&gt;&lt;h2 id=&quot;related-resources&quot;&gt;Related Resources&lt;/h2&gt;&lt;p&gt;This article has focused on what I’ve found is one of the more prickly problems in setting up a good card sort. For a broader overview of card sorting in general, and for more information on choosing card sort methods, recruiting participants, and analyzing results, check out these excellent resources:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;&lt;a href=&quot;https://www.nngroup.com/articles/card-sorting-terminology-matches/&quot;&gt;Card Sorting: Pushing Users Beyond Terminology Matches&lt;/a&gt; | NN/g&lt;/li&gt;&lt;li&gt;&lt;a href=&quot;https://www.nngroup.com/articles/card-sorting-definition/&quot;&gt;Card Sorting: Uncover Users’ Mental Models for Better Information Architecture&lt;/a&gt; | NN/g&lt;/li&gt;&lt;li&gt;Card Sorting 101 | Optimal Workshops&lt;/li&gt;&lt;li&gt;&lt;a href=&quot;https://blog.optimalworkshop.com/how-to-pick-cards-for-card-sorting/&quot;&gt;How to pick cards for card sorting&lt;/a&gt; | Optimal Workshops&lt;/li&gt;&lt;li&gt;&lt;a href=&quot;https://www.usability.gov/how-to-and-tools/methods/card-sorting.html&quot;&gt;Card Sorting&lt;/a&gt; | Usability.gov&lt;/li&gt;&lt;/ul&gt;</content>
  </entry>
  <entry>
    <title type="text">Delivering Information Architecture</title>
    <link rel="alternate" type="text/html" href="https://preview.andyfitzgeraldconsulting.com/insights/delivering-ia/"/>
    <id>https://preview.andyfitzgeraldconsulting.com/insights/delivering-ia/</id>
    <published>2020-04-29T00:00:00Z</published>
    <updated>2020-04-29T00:00:00Z</updated>
    <summary type="text">A deep dive into delivering effective IA and staying focused on the right problems.</summary>
    <category term="Perspective"/>
    <category term="Information Architecture"/>
    <category term="Interoperability"/>
    <category term="Systems Thinking"/>
    <content type="html">&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/8169956af3be8fa1d33b4d4192ca31c7ab55babe-1300x500.jpg?rect=206,0,888,500&amp;amp;w=888&amp;amp;h=500&amp;amp;fit=crop&amp;amp;auto=format&quot; width=&quot;888&quot; height=&quot;500&quot; alt=&quot;A creative photograph of a cityscape focused within the lens of a camera held by a hand, with the blurry background of the sunset sky and city buildings outside the lens.&quot; /&gt;&lt;/figure&gt;&lt;p&gt;One of the greatest challenges in digital design is identifying and maintaining focus on the right problem. For information architecture, one of our most common deliverables, the visual sitemap, can actually make focusing on the right problems harder, if not impossible. In this article we’ll examine why this happens, explore what practitioners and teams can do to avoid this trap of misplaced focus, and learn how to rehabilitate our wayward sitemaps and reinstate them as the effective design artifacts they can be.&lt;/p&gt;&lt;p&gt;One of the greatest challenges in digital design is identifying and maintaining focus on the right problem. The temptation to spend energy on problems that are &lt;em&gt;urgent&lt;/em&gt; (but not important), &lt;em&gt;interesting&lt;/em&gt; (but not impactful), or &lt;em&gt;easy&lt;/em&gt; (but not relevant) is difficult to avoid—and sometimes even difficult to detect.&lt;/p&gt;&lt;p&gt;For information architecture, such misplaced focus can lead to a range of problems. I’ve come across clients who end up with an expensive, full function CMS of which they’re only using the most basic features and capabilities because their information layer is a mess. Or clients who migrated to a new platform (with a shiny new visual design) which worked well for a year or so, but as they added content and adapted to market conditions, the structure crumbled and now customers can’t find anything. And, of course, we’ve all seen—or been the victims of—intranets put together by some well-meaning colleague who, despite their best intentions, ended up creating a reviled object of misery and loathing.&lt;/p&gt;&lt;p&gt;Though problems such as these stem from a series of interrelated circumstances and decisions, the shared thread that runs through them is an underestimation of the scope and impact of information architecture. This is a common result when practitioners and teams focus on &lt;em&gt;the arrangement&lt;/em&gt; of resources and functionality, but ignore the &lt;em&gt;method of arrangement&lt;/em&gt; that generates that final result.&lt;/p&gt;&lt;p&gt;The beguiling light that leads us into this dark corner of despair is, all too often, the most ubiquitous of IA deliverables: the visual sitemap. In this article we’ll examine why this happens, explore what practitioners and teams can do to avoid this trap of misplaced focus, and learn how to rehabilitate our wayward sitemaps and reinstate them as the effective design artifacts they can be.&lt;/p&gt;&lt;h2 id=&quot;devils-details-and-sitemaps&quot;&gt;Devils, Details, and Sitemaps&lt;/h2&gt;&lt;p&gt;In his whimsical 1975 systems engineering treatise, systems theorist John Gall writes that “a complex system that works is invariably found to have evolved from a simple system that works.”&lt;/p&gt;&lt;p&gt;Most websites today are indisputably complex systems. This is clearly the case with sites running on enterprise CMSs and connected to integrated commerce, tracking, and analytics tools. Even for sites that are built on much simpler code bases, however, we must still negotiate the needs of users, the goals of the business, and the opportunities and constraints presented by the underlying technology.&lt;/p&gt;&lt;p&gt;There is a wide—and ever growing—variety of tools and techniques at our collective disposal for working through these complex systems. In spite of (or perhaps because of) this expansive toolkit, the IA deliverable that most resonates with clients, and the only one which, as a fairly well-seasoned IA, I am ever regularly asked to produce, is the visual site map.&lt;/p&gt;&lt;p&gt;Visual sitemaps are the “org chart” styled diagrams that are often used to communicate website hierarchy, navigation, and sometimes even layout and template specifications. Though framed in the early literature as just one element of the well-rounded IA practitioner’s toolkit, visual sitemaps have recently begun taking on a life of their own. In the last couple years, for instance, there has been a dramatic &lt;a href=&quot;https://getfoundonline.in/top-8-visual-sitemap-generators-for-better-site-architecture/&quot;&gt;uptick in visual sitemap SAAS tools&lt;/a&gt; designed specifically to speed up—and in some cases automate—the site map diagram creation process. (Claims one: “Create your visual sitemap on the go—easy peasy!”)&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/18271d0b30502f0ba0614dd97cbbc66c12f42716-1300x814.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;751&quot; alt=&quot;Screenshot of Google image search showing results for visual sitemap generator tools, many images showing basic, rudimentary visual sitemaps.&quot; /&gt;&lt;figcaption&gt;Visual sitemap generator tools circa 2020&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;The appeal of visual sitemaps is easy to understand. Organizations &lt;em&gt;love&lt;/em&gt; org charts (and why not? they’re essentially “selfies” for corporations), and visual site maps are based on the same diagrammatic model. Visual sitemaps provide a flat, simplified model of what a website, intranet, or application looks like from the home page at a given point in time. This affords a perspective from which even the most technologically unsavvy stakeholder or team member can offer feedback, suggestions, and critique. Visual sitemaps feel important and impactful, and, as their completion usually marks the point in a project when development can get started, they certainly feel urgent.&lt;/p&gt;&lt;p&gt;When we break down the design decisions that a visual sitemap represents, however, we can see clear evidence of the complex interplay of a number of underlying systems. Here, for example, is a site map I created for the University of Washington in 2011:&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/70806452d1ced85335a4a263bafcbe052aea48f5-1300x978.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;903&quot; alt=&quot;A simple black and white visual sitemap show ing the basic structure of the UW Simpson Center for the humanities website. Includes top level categories for What&amp;#x27;s New, Programs, Projects, Media and Communication, Apply for Support, and About, with multiple subcategories beneath each.&quot; /&gt;&lt;figcaption&gt;Visual sitemap for the UW Simpson Center for the Humanities, created in 2011&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;As far as sitemaps go, this one’s fairly simple. It still, however, represents at least four distinct systems that must interoperate predictably and reliably in order to create an effective and sustainable website:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;classification&lt;/li&gt;&lt;li&gt;navigation&lt;/li&gt;&lt;li&gt;global layout&lt;/li&gt;&lt;li&gt;page type&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;Some of these systems, such as page type, are usually worked through in greater detail elsewhere in the design process. Too often, however, the site map is the centerpiece of discussions about categorization, classification, prioritization, arrangement, and navigation. This forces us to attempt to make decisions about making the complex system work, as opposed to focusing on how to make sure the simple systems work.&lt;/p&gt;&lt;p&gt;This is a problem. For the rudimentary site map above, for instance, there are at least 15 points of overlap between the four systems it represents:&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/1cacc062988ad2913aea13af5566d0e55cd90ab6-2600x1188.png?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;548&quot; alt=&quot;A four set Venn diagram, showing the 15 instances of overlap between sets.&quot; /&gt;&lt;figcaption&gt;A four set Venn diagram&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;This is a lot to take in even for sharp people on a good day—and that’s &lt;em&gt;if&lt;/em&gt; you can get your team’s and stakeholders’ time and attention for long enough to explain it.&lt;/p&gt;&lt;p&gt;Because sitemaps are poor vehicles for evaluating whether the simple systems that make up a website are working as intended, what we often end up discussing is the &lt;em&gt;arrangement of the pages we see&lt;/em&gt;, as opposed to the decisions, priorities, and rules that define the &lt;em&gt;methods for arranging them&lt;/em&gt;. We substitute a discussion about the important, impactful, and relevant details of how the information design and delivery system works (or should work), for an urgent, interesting, and easy conversation about whose section has a link in the global nav, or where individual pages will “live” on the new site.&lt;/p&gt;&lt;p&gt;This &lt;em&gt;feels&lt;/em&gt; like design, but from a systems point of view, all we’ve done is take a snapshot of the machine at rest, from the outside. In these cases, we only see how the system actually works after it’s been built and is working for—or failing—our customers and business.&lt;/p&gt;&lt;h2 id=&quot;creating-simple-systems-that-work&quot;&gt;Creating Simple Systems That Work&lt;/h2&gt;&lt;p&gt;The problem with making mission critical decisions about a complex system as a whole is that we’re lousy at understanding and evaluating systems in detail. The solution to this frustrating state of affairs is evident in Gall’s law: if a complex system that works is invariably composed of simple systems that work, we must ensure that the simple systems that come together to make our complex system work as we intend them to. (Implicit here is a corollary I’ve formulated to Gall’s Law: All systems “work”; they just don’t always work as we intend them to.)&lt;/p&gt;&lt;p&gt;When it comes to designing information systems for use online, the Web’s underlying technologies can help us isolate these “simple systems.” The &lt;a href=&quot;https://tools.ietf.org/html/rfc1738&quot;&gt;1994 RFC defining URLs&lt;/a&gt;, for instance, describes the hierarchical nature of URL schemes and outlines the fundamental way that meaning is created with structure on the web. The &lt;a href=&quot;https://tools.ietf.org/html/rfc1866&quot;&gt;RFC describing Hypertext Markup Language&lt;/a&gt; likewise defines the primary way that HTML documents and other resources are linked and accessed on the web.&lt;/p&gt;&lt;p&gt;These fundamental building blocks give us a way to consider the smaller systems that combine to create a holistic information architecture approach—in this example, classification (as defined by URL directory structure) and navigation (as defined by purposeful systems of hyperlinks). By focusing on these smaller operational components, we can work to ensure that these simple systems work as we intend by using a principled, standards-based approach to interrogate, understand, and optimize them in order to better meet user and business goals within the context of the technology and resources available to us.&lt;/p&gt;&lt;p&gt;Let’s look at an example of how this works in practice. I recently helped an international technical consulting firm consolidate two independent and distinct websites into a single, cohesive web presence that would serve their customers worldwide. I can’t share the &lt;em&gt;actual&lt;/em&gt; work I did for this client, but I did use it as the real-world inspiration for a &lt;em&gt;fictional&lt;/em&gt; consulting company that I can discuss: Aldrin Lunar.&lt;/p&gt;&lt;p&gt;“Aldrin Lunar” is an extra-planetary exploration and stewardship consultancy. They help companies in the emerging field of private sector space exploration make sound business decisions around strategy and technology. Up until this year, they had actually been two companies—Aldrin Astronautics and Lunar Strategies International—who often worked in close association, but maintained separate brands (and websites). They hired me to help them consolidate their websites into a single, cohesive experience for their clients and potential clients worldwide.&lt;/p&gt;&lt;h3 id=&quot;classification-scheme&quot;&gt;Classification Scheme&lt;/h3&gt;&lt;p&gt;One of the core deliverables I created for Aldrin Lunar is a classification scheme. Classification schemes define, order, and establish rules for a digital property’s core system of classification. Classification is how a website communicates meaning in the way content is organized to users and to search engines. The choice and relationship of categories tells a story about a brand, a collection of content, and an organization’s priorities and values.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/5d731501ab286d9bc1a1ffc5c5b52b991fcf545d-1300x812.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;750&quot; alt=&quot;An image of a spreadsheet containing classification specifications for the fictional Aldrin Lunar website.&quot; /&gt;&lt;figcaption&gt;The Aldrin Lunar classification scheme&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;In order to define a classification scheme that would meet Aldrin Lunar’s business goals, effectively serve their users, and reflect their unique skills and values, I used a principled, standards-based process to design, iteration, and documentation.&lt;/p&gt;&lt;p&gt;A “principled” approach to design works to ensure that evidence and the interpretation of evidence gathered in discovery and research phases aligns with and supports classification recommendations. In the case of Aldrin Lunar, we used the &lt;em&gt;warrant principles&lt;/em&gt; to ensure that the categories chosen and the labels assigned to them were justified by the evidence we had gathered in research and discovery phases:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;&lt;strong&gt;Literary warrant:&lt;/strong&gt; the classification method recommended must be based only on the specific resources being classified&lt;/li&gt;&lt;li&gt;&lt;strong&gt;Scientific warrant:&lt;/strong&gt; only those categories recognized by experts in the domain should be used in the classification system&lt;/li&gt;&lt;li&gt;&lt;strong&gt;User warrant:&lt;/strong&gt; categories and descriptive terms should be chosen according to their frequency of use by everyone—not just domain experts&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;Even from this short list it is clear to see that any given set of principles will often conflict. This is what makes this a design process, as opposed to simply a rote application of rules. By framing discussions of classification in terms of warrant principles, we were able to keep our conversations—and decisions—based on the needs of priorities of users and the business.&lt;/p&gt;&lt;p&gt;This alone, however, isn’t enough to ensure that the &lt;em&gt;system&lt;/em&gt; of classification works as intended. We also needed a set of standards to guide the framing of our findings and recommendations. Classification, when done right, feels “obvious,” which tends to create the impression that formulating it should be equally obvious. The astounding number of confusing, poorly organized websites (and intranets) makes a strong argument that this is &lt;em&gt;not&lt;/em&gt; the case. To create a classification system that works as intended, and reflects Aldrin Lunar’s unique business and services, we needed to ensure that it conforms to the ways that humans of varying skill levels process linguistic terms, categories, and relationships.&lt;/p&gt;&lt;p&gt;This is where standards help to inform our design. Published standards represent the distilled wisdom of subject matter experts worldwide. They help to ensure that a design solution meets accepted interoperability and compatibility standards, but more than that, they allow assiduous practitioners to introduce top level expertise to a project of any size (or budget).&lt;/p&gt;&lt;p&gt;For Aldrin Lunar we used &lt;a href=&quot;https://www.iso.org/standard/50340.html&quot;&gt;ISO/IEC 11179-3 - Registry Metamodel and Basic Attributes&lt;/a&gt; and &lt;a href=&quot;https://www.niso.org/publications/ansiniso-z3919-2005-r2010&quot;&gt;ANSI/NISO Z39.19 - Guidelines for the Construction, Format, and Management of Monolingual Controlled Vocabularies&lt;/a&gt; to inform our creation of a set of categories—and rules for how those categories operate and evolve—that provides a stable, predictable foundation for the website. Because it is designed as a system for arranging resources based on business and user needs, as opposed to a single arrangement of current resources, it is able to flex and grow as the needs of the company and its customers change over time.&lt;/p&gt;&lt;h3 id=&quot;navigation-model&quot;&gt;Navigation Model&lt;/h3&gt;&lt;p&gt;A navigation model represents a recommended navigation scheme and labeling system for a website or application. In the same way that the classification scheme corresponds to the underlying web technology of URLs, the navigation model corresponds to the way the web is connected via links, the “hypertext” in HTML.&lt;/p&gt;&lt;p&gt;For Aldrin Lunar, this includes documenting the site’s primary and secondary global navigation, global footer navigation, and category-specific primary local navigation.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/d4b5c8592afaffbc72bc5bca627bc0dfd321420e-1300x812.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;750&quot; alt=&quot;An image of a spreadsheet containing navigation specifications for the fictional Aldrin Lunar website.&quot; /&gt;&lt;figcaption&gt;The Aldrin Lunar navigation model&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;You may be surprised that the navigation model is documented in a spreadsheet, as opposed to being mocked up as part of an interface in a wireframing or drawing tool. This is an explicit choice: by stripping navigation down to its constituent elements—link, label, grouping, and order—we can evaluate and optimize the simple system that is later combined with graphic user interface elements to create a more complex system. This means that our information architecture can give UX and UI designers a solid, functional foundation on which to build, but without locking them into interface choices.&lt;/p&gt;&lt;p&gt;Translating a navigation model across form factors offers an example of why this is important. On desktop/laptop screens, for instance, one common way to communicate to site visitors that a global menu is “secondary” is to format it in smaller type, and place it close to the top edge of the screen.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/74ce2d7c2010be7fc4695935b81ac56299000b4c-1300x834.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;770&quot; alt=&quot;Positions, Locations, and Pressroom displayed as secondary global navigation on an Aldrin Lunar desktop wireframe&quot; /&gt;&lt;figcaption&gt;Positions, Locations, and Pressroom displayed as secondary global navigation on an Aldrin Lunar desktop wireframe&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;On mobile, however, that same menu is placed below primary global navigation to communicate that it is secondary, and the type size of both menus is closer together to support better mobile usability.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/0346502a3811b6e6f49c3e031c3a84ecbd375a0f-1300x800.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;738&quot; alt=&quot;Secondary global navigation on a mobile device&quot; /&gt;&lt;figcaption&gt;Secondary global navigation on a mobile device&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;These are not differences in the navigation model; they’re differences in how that model is expressed consistently across contexts. By designing the navigation model first as a system bounded by the core technologies of the web (hypertext), we better our chances of starting with a simple system that works, before compounding its complexity by combining it with other systems.&lt;/p&gt;&lt;p&gt;As with the classification scheme, we can use a principled, standards-based process to design, iterate, and document navigation. The warrant principles we looked at earlier apply to navigation design, but since navigation focuses more heavily on the idiosyncrasies of potential site visitors across sometimes very different user groups, we’ll also want to incorporate principles that take into account the sometimes quirky nature of human perception and comprehension.&lt;/p&gt;&lt;p&gt;The &lt;a href=&quot;https://www.interaction-design.org/literature/book/the-glossary-of-human-computer-interaction/gestalt-principles-of-form-perception&quot;&gt;Gestalt principles of form perception&lt;/a&gt; translate in some important and useful ways to information design. The law of &lt;a href=&quot;https://www.interaction-design.org/literature/article/the-law-of-similarity-gestalt-principles-1&quot;&gt;similarity&lt;/a&gt;, for instance, applies to word forms for labels. Imperative word forms like “shop,” “learn more,” and “sign up” form a conceptually distinct group, as opposed to declarative word forms like “news,” “events,” and “services.”&lt;/p&gt;&lt;p&gt;The gestalt law of &lt;a href=&quot;https://www.interaction-design.org/literature/article/the-laws-of-figure-ground-praegnanz-closure-and-common-fate-gestalt-principles-3&quot;&gt;common fate&lt;/a&gt;, likewise helps make the case that link targets in a distinct menu should behave the same. When five of six global navigation links lead to on-site landing pages, but the sixth takes you to a different website altogether, the effect is jarring. This isn’t to say that this could never be done. Understanding and optimizing navigation at a conceptual level prior to interface design, however, allows you to work through the fundamental behavior of this simpler system first, and to ensure that the result is what you intend.&lt;/p&gt;&lt;p&gt;A useful standard for this process is &lt;a href=&quot;https://www.iso.org/standard/77520.html&quot;&gt;ISO 9241-210 - Human Centered Design for Interactive Systems&lt;/a&gt;, which recommends identifying clear goals, incorporating evaluation, and integrating user feedback into an iterative, multi-part cycle.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/e2640ecfb7e2ca6085cfea3a5cea09b94d09be86-1300x800.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;738&quot; alt=&quot;A schematic showing the basic steps of the human centered design process described by ISO 9241&quot; /&gt;&lt;figcaption&gt;The human centered design process, ISO 9241-210&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;For Aldrin Lunar, applying this standard meant performing frequent, lightweight tests throughout the design process to ensure that iterations were actually improving the navigation model. In early phases of project work, for instance, the &lt;a href=&quot;https://www.optimalworkshop.com/treejack/&quot;&gt;Treejack&lt;/a&gt; tool from Optimal Workshop provided a low cost, easily deployable option for getting frequent feedback and evaluating the effects of changes to the concept.&lt;/p&gt;&lt;p&gt;Later in the process we also tested navigation with low fidelity clickable wireframes, which led to further iterations and improvements. Having taken the time to refine the navigation model early on helped streamline these tests and allowed us to focus on how UX and UI decisions were impacting the model. This had a double advantage of allowing us to concentrate on the simple system first, and allowing us to confidently cut down the scope of later prototype testing, which was more expensive to set up and run.&lt;/p&gt;&lt;h2 id=&quot;visual-sitemaps-revisited&quot;&gt;Visual Sitemaps Revisited&lt;/h2&gt;&lt;p&gt;The classification scheme and navigation model are not the only simple systems in digital information design work. Depending on the project, one might also create content models, application profiles and custom taxonomies, linked data models, and many other kinds of artifacts. In all cases, the choice to use any (or all) of these approaches stems from a clearly identified problem in need of solving. Any kind of one-size-fits-all laundry list of deliverables is bound to make a project sponsor skeptical—and with good reason.&lt;/p&gt;&lt;p&gt;I likewise don’t use the two “simple system” approaches to delivering information architecture I’ve presented here on every project; not all projects call for them. When I am asked to “deliver a sitemap,” however, these are among the most effective methods I’ve found for making sure that the design work behind the site map actually gets done, and delivering that work in a way that externalizes my and my team’s collective discovery, understanding, and optimization recommendations.&lt;/p&gt;&lt;p&gt;That said, I do also create, present, and deliver visual sitemaps. The sitemap I created for Aldrin Lunar helped socialize recommendations and drive conversations about iterations, improvements, and trade-offs.&lt;/p&gt;&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/cf3ade8042483e7a9cc24eab651c098b6d7b6095-1300x832.jpg?w=1200&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;768&quot; alt=&quot;A simple visual sitemap of the Aldrin Lunar website&quot; /&gt;&lt;figcaption&gt;A visual sitemap of the Aldrin Lunar website, used to discuss information architecture recommendations&lt;/figcaption&gt;&lt;/figure&gt;&lt;p&gt;The difference between a visual sitemap backed by simple-systems work, and a visual sitemap carrying all the weight of design on its own, however, is profound. In the latter case, there is no available way to disentangle the complex system and engage its constituent parts. The tendency to engage with the &lt;em&gt;arrangement&lt;/em&gt; is overwhelming.&lt;/p&gt;&lt;h3 id=&quot;visual-sitemaps-productive-conversations&quot;&gt;Visual Sitemaps &amp;amp; Productive Conversations&lt;/h3&gt;&lt;p&gt;When the concepts, rules, and decisions that animate the operation of the system have been worked through and can be readily examined in detail, an informed conversation about the method of arrangement is possible. On the Aldrin Lunar project, for example, one stakeholder, on seeing the visual sitemap, declared that there was no way “projects” (case studies) could be omitted from global navigation. “Projects are what we are—they’re everything we do,” she said.&lt;/p&gt;&lt;p&gt;Because of the principled, standards-based process that led to that design recommendation, instead of arguing over conflicting points of view about the arrangement of that particular piece of content, we were able to discuss how the system as a whole promoted the stakeholder’s goal. For this stakeholder, project case studies are &lt;a href=&quot;https://en.wikipedia.org/wiki/Metonymy&quot;&gt;&lt;em&gt;metonymically&lt;/em&gt;&lt;/a&gt; related to “everything Aldrin Lunar does”; they are a stand-in for the detailed understanding of Aldrin Lunar’s skills and expertise that she knows potential clients can &lt;em&gt;find&lt;/em&gt; in those case studies.&lt;/p&gt;&lt;p&gt;Once we pulled this relationship apart, we could all clearly agree that this stakeholder’s interest—clearly communicating Aldrin Lunar’s skills and expertise—is paramount. Then we could productively engage in a principled conversation about which strategy for communicating that content would be most effective, given what we know about how visitors use the site.&lt;/p&gt;&lt;p&gt;In this example, for instance, “project” is a useful category in the classification scheme because it lends itself to better indexing and findability on the part of algorithms, effectively stores content that will be republished in a variety of views across the site, and simplifies the author workflow. It doesn’t, however, necessarily make a good candidate for a global navigation label. Aldrin Lunar website visitors don’t come to the site to read “project case studies”; they come to learn about Aldrin Lunar’s expertise in Exploratory Stewardship, or Go to Market, or Strategy.&lt;/p&gt;&lt;p&gt;This is the rationale for not surfacing the content format “projects” as a menu item, but rather surfacing those case studies in the context of industries and expertise, in order to make the &lt;a href=&quot;https://www.nngroup.com/articles/information-scent/&quot;&gt;information scent&lt;/a&gt; of what the case studies contain stronger. This allows the site to systematically show relevant content to site visitors once they’re communicated some initial information about what they hope to learn (for example, by clicking on “Extraplanetary Stewardship” in the “Expertise” menu).&lt;/p&gt;&lt;p&gt;As a result of this conversation, the project team (including this particular stakeholder) had a better understanding of the method of arrangement created by the interaction of simple systems. This meant we could all then focus on how that method either supported user and business goals—or how we might refine its individual elements to improve its performance as a holistic system.&lt;/p&gt;&lt;h3 id=&quot;delivering-ia-purposefully-intentionally&quot;&gt;Delivering IA Purposefully &amp;amp; Intentionally&lt;/h3&gt;&lt;p&gt;This way of delivering information architecture may add some new steps to your design process. To some, it may look like unnecessarily drawing out something that’s “really not that complicated.” To be fair, if you truly have a simple digital property—a simple campaign page, or single topic blog—the combination of all its pieces may be simple enough to understand as a composite. Likewise, if you have a digital property that doesn’t have to work as intended on launch, you may be able to iterate toward an effective system by measuring performance and improving iteratively after the fact.&lt;/p&gt;&lt;p&gt;If, however, your digital property serves a critical business, social, or humanitarian function, it is worth taking the time to focus on how its constituent systems work and understand the results their interplay produces. Every website, application, and intranet &lt;em&gt;has&lt;/em&gt; an information architecture. Some are created by design; some are created by default. By providing yourself and your team with the tools to focus on important, impactful, and relevant problems, you can help to ensure that the IA you produce is intentional, purposeful, and by design.&lt;/p&gt;</content>
  </entry>
  <entry>
    <title type="text">Four Web Writing Style Guides from which to Borrow</title>
    <link rel="alternate" type="text/html" href="https://preview.andyfitzgeraldconsulting.com/insights/web-writing/"/>
    <id>https://preview.andyfitzgeraldconsulting.com/insights/web-writing/</id>
    <published>2020-04-20T00:00:00Z</published>
    <updated>2020-04-20T00:00:00Z</updated>
    <summary type="text">Get started with web writing with this intro, template, and set of examples.</summary>
    <category term="Method"/>
    <category term="Governance"/>
    <category term="Best Practices"/>
    <category term="Digital Communication"/>
    <content type="html">&lt;figure&gt;&lt;img src=&quot;https://cdn.sanity.io/images/7v0qvet6/production-26/3f70c2c7b61e3d748ccb0954930d27821e55bc58-1262x840.jpg?rect=0,0,1262,710&amp;amp;w=1200&amp;amp;h=675&amp;amp;fit=crop&amp;amp;auto=format&quot; width=&quot;1200&quot; height=&quot;675&quot; alt=&quot;Vintage typewriter with a sheet of paper half covered in text loaded in&quot; /&gt;&lt;/figure&gt;&lt;p&gt;It is a truth universally acknowledged, that a website in possession of a shiny new design, must be in want of good content. Unfortunately, the process of auditing, revising, migrating, and creating quality content can be daunting. Style guides can help! Here&amp;#x27;s a brief intro to web writing style guides&amp;amp;mdash;and a quick way to get started with creating your own.&lt;/p&gt;&lt;p&gt;It is a truth universally acknowledged, that a website in possession of a shiny new design, must be in want of good content. Unfortunately, the process of auditing, revising, migrating, and creating quality content can be daunting. This is why it often gets left to the end of a project and then frantically hashed out in last minute skirmishes over what’s “good enough for now.”&lt;/p&gt;&lt;p&gt;The value gained from quality content—to say nothing of an effective content strategy—is well worth the price of engaging seasoned content professionals early on and heeding their advice. Nonetheless, there are a few DIY steps that even small or resource strapped teams can take to ensure that content effectively meets the needs and proclivities of users and business alike. One of these steps is to create a web writing style guide.&lt;/p&gt;&lt;h2 id=&quot;meet-the-web-writing-style-guide&quot;&gt;Meet the Web Writing Style Guide&lt;/h2&gt;&lt;p&gt;A web writing style guide helps content creators and revisers write effectively for the web and in a style that is consistent with an organization’s brand and image. We all know “how to write,” of course, but writing content for the web is different than writing reports, presentations, or email. Writing content for broad consumption in the “voice” of an organization or brand is also not something that most folks tasked with “helping out with the content updates” have much experience with.&lt;/p&gt;&lt;p&gt;A style guide reduces the effort needed to create quality content by bridging these knowledge and experience gaps. Style guides are sometimes framed as “enforcement tools,” but I like to think of them more as a cheat sheets. Once a style guide is created, content creators don’t have to make decisions about case, or voice, or sentence length, or target vocabularies. They can instead focus on creating good content that creates value for their readers by effectively conveying information.&lt;/p&gt;&lt;h2 id=&quot;creating-a-style-guide-of-your-very-own&quot;&gt;Creating a Style Guide of Your Very Own&lt;/h2&gt;&lt;p&gt;Style guides can range in scope from a few printed pages, to scores of sections on a dedicated sub-site. If you’re just starting out in creating a web writing style guide for your organization or project, don’t let the expansiveness of guides on dedicated sites discourage you. Rather, use these as resources from which to borrow parts to create a starting point for the guide your content creators need. From that foundation you can build and fine tune over time—none of the comprehensive guides you see online sprung into existence all at once.&lt;/p&gt;&lt;p&gt;Here are four guides to help you get started:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;&lt;a href=&quot;https://styleguide.mailchimp.com/&quot;&gt;Mailchimp Content Style Guide&lt;/a&gt;. Mailchimp’s guide is a feast of writing advice both for the web in general and for channeling Mailchimp’s distinct style. If you borrow material form the latter category, be sure it fits with the voice of your organization. Mailchimp’s guide is definitely on the “comprehensive” end of the spectrum. Mercifully, it also includes an excellent &lt;a href=&quot;https://styleguide.mailchimp.com/tldr/&quot;&gt;one-page TL;DR&lt;/a&gt;.&lt;/li&gt;&lt;li&gt;&lt;a href=&quot;https://www.gov.uk/guidance/content-design/writing-for-gov-uk&quot;&gt;Gov.UK Content Design Guide&lt;/a&gt;. The Gov.UK guide provides excellent “web writing in general” resources, as well as journalistic direction for those writing for the UK’s government sites. Short sections with salient subtitles, examples, and bulleted lists make this guide easy to understand—and easy to borrow from.&lt;/li&gt;&lt;li&gt;&lt;a href=&quot;https://www.bbc.co.uk/academy/en/collections/news-style-guide&quot;&gt;BBC News Style Guide&lt;/a&gt;. This BBC guide is less geared toward writing for the web and focuses instead on fostering consistency when there are a lot of authors involved. It does this by providing guidance on capitalization, pluralization, homophones, and preferred spellings. Consistency at this level helps create a coherent “voice” without an overtly branded character (such as one sees with Mailchimp). Most organizations won’t need as &lt;em&gt;much&lt;/em&gt; direction as the BBC provides here, but including direction around a few high-impact elements can go a long way to heading off collisions in mechanics and style.&lt;/li&gt;&lt;li&gt;&lt;a href=&quot;https://www2.ed.gov/web-guidance/styleguide/words.html&quot;&gt;US Department of Education&lt;/a&gt;. This concise, easily scannable guide covers the most basic elements of writing for readability, findability, and comprehension on the web. It also links out to the sources that support its recommendations. This is an excellent way to position a writing guide as a resource for writers, rather than as a constraint on them.&lt;/li&gt;&lt;/ul&gt;&lt;h2 id=&quot;bringing-it-all-together-and-one-more-example&quot;&gt;Bringing It All Together (And One More Example)&lt;/h2&gt;&lt;p&gt;How you bring your guide together will depend on the needs and goals of your project and organization. A recent client of mine, for example, wanted a style guide they could easily print out so they didn’t need yet another thing on screen as they were revising content. I created a document informed by our research—and helped out by some of the sources above—that was easily scannable and fit on two double-sided pages. For this project, I also included guidance on the use of targeted keywords, since this was an important element of our redesign process. I’ve posted a &lt;a href=&quot;https://docs.google.com/document/d/1ZBoJHFY0yC3QB7VqmlXn-pP4va0EQUQSsiBwusqSk4A/edit?usp=sharing&quot;&gt;lightly scrubbed version of this guide in Google Docs&lt;/a&gt; for your perusal (and, of course, borrowing).&lt;/p&gt;&lt;p&gt;Once you have the basics down, you now have a foundation upon which to build. Sarah Richards’s &lt;a href=&quot;https://www.amazon.com/Content-design-Sarah-Richards/dp/1527209180&quot;&gt;&lt;em&gt;Content Design&lt;/em&gt;&lt;/a&gt; is an excellent resource for moving your content design process to the next level. Still feeling a bit overwhelmed? Please do drop me a note below; I’d love to hear more about your project and chat about how I can help.&lt;/p&gt;</content>
  </entry>
</feed>
