The how: Building the site structure

Putting all of the content pieces together.

My initial site architecture was based on the existing architecture in WordPress:

Very few parts of this structure ended up in the new site. If you’ve ever revamped lots of legacy content, this probably isn’t surprising.

Content types

In support of this architecture, I designed three main content types (page types):

Content reuse

Using metadata and collections enables reuse. Copy-pasted content across pages is a maintenance nightmare. Someone has to remember to update it, and also all the places where the content is pasted.

Metadata

Most technical writers and content strategists are familiar with metadata (also referred to as front matter or frontmatter). You can use it to define page titles, keywords, tags, and categories right out of the box. The real power comes by adding custom metadata; highly structured content expands the possibilities of the template engine and site generator.

When I built out this site, I wanted to re-use the first sentence of each details page to display as descriptions on the cards on the grid pages. This also allowed me to style the descriptions separately.

---
title : 'The how: Building the site structure'
description : Putting all of the content pieces together.
tags : content-strategy
featured : true
featuredOrder : 3
FontAwesomeIcon : solid fa-file-waveform
---
Fieldname Purpose
title Page title that displays on cards, grids, and details pages, and browser tabs.
description The first paragraph of the story used many places.
FontAwesomeIcon Programmatically displays an icon on the homepage, grid pages, and breadcrumbs.
featured sets the card to display on the homepage.
featuredOrder Sets the order in which the card displays.

Here’s an example of how this content works programmatically. Note the backslashes are necessary to get the code to display.

    <div class="bg-whitish p-4">
        <h3 aria-labelledby="\{\{ item.data.title |slugify }}">
            \{\% if item.data.FontAwesomeIcon %}
                <span class="fa- text-2xl text-medium-blue"></span>
            \{\% endif %}
            \{\% if item.data.cover %}
                <img src="/assets/images/" alt="\{\{ item.data.coverAlt or item.data.title }}" data-pagefind-meta="image[\{\{item.data.cover}}], image_alt[\{\{ item.data.coverAlt or item.data.title }}]" class="w-full h-48 object-cover mb-2">
            \{\% endif %}
            <a href="\{\{ item.url }}">\{\{ item.data.title | safe }}</a>
        </h3>
        <p>\{\{ item.data.description }}</p>
    </div>

This code generates cards that references the metadata fields. You can view the clean code at lines 68-82 of macros.njk.

Here’s what two cards side-by-side look like:
Example result of card code

Separating content from presentation

While these don’t really apply to my use case, trying to abstract as much as possible taught me:

Exploration

There was a lot of experimenting and seeing what was what. Once I grasped how to use the metadata programmatically, it opened my eyes to how much structured front matter makes a difference in how content is used, sorted, filtered, and displayed.

While I was building out the site there were grid template pages for each of those content types. Eventually I made the grid collection-agnostic.

Then I added two json files to pull data from:

This let me leverage the built-in category metadata to populate each skills page with the relevant work and tools I used. It was fun, refreshing, and again, holy cow structured content.

[
  {
    "category": ["docs-as-code", "coding-experience", "technical-writing"],
    "publisher": "Nunjucks",
    "title": "Nunjucks templating engine"
  },
  {
    "category": ["technical-writing", "image-editing"],
    "publisher": "Adobe",
    "title": "Photoshop"
  },
  {
    "category": ["technical-writing", "page-layout", "structured-authoring"],
    "publisher": "Adobe",
    "title": "FrameMaker"
  },
  {
    "category": ["technical-writing", "knowledge-management"],
    "publisher": "Adobe",
    "title": "Captivate"
  },
  {
    "category": ["technical-writing", "help-authoring-tool"],
    "publisher": "Adobe",
    "title": "RoboHelp"
  },
  {
    "category": ["technical-writing", "help-authoring-tool"],
    "publisher": "Adobe",
    "title": "Acrobat Pro"
  },

  {
    "category": ["content-strategy", "metrics"],
    "publisher": "Screaming Frog",
    "title": "Screaming Frog SEO Spider"
  },
  {
    "category": ["content-strategy", "metrics", "information-architecture"],
    "publisher": "Microsoft",
    "title": "Excel"
  },
  {
    "category": [
      "technical-writing",
      "help-authoring-tool",
      "coding-experience"
    ],
    "publisher": "Open-source",
    "title": "HTML"
  },
  {
    "category": ["technical-writing", "help-authoring-tool"],
    "publisher": "OpenAPI",
    "title": "OpenAPI (Swagger)"
  },
  {
    "category": ["podcasting", "audio-editing", "audio-production"],
    "publisher": "Adobe",
    "title": "Audition"
  },
  {
    "category": ["podcasting", "audio-editing", "audio-production"],
    "publisher": "Open-source",
    "title": "Audacity"
  },
  {
    "category": ["technical-writing", "page-layout"],
    "publisher": "Adobe",
    "title": "InDesign"
  },
  {
    "category": [
      "docs-as-code",
      "product-management",
      "agile",
      "technical-writing"
    ],
    "publisher": "Atlassian",
    "title": "Jira"
  },
  {
    "category": ["technical-writing", "knowledge-management"],
    "publisher": "Atlassian",
    "title": "Confluence"
  },
  {
    "category": ["metrics", "content-strategy"],
    "publisher": "Elasticsearch",
    "title": "Kibana"
  },
  {
    "category": ["technical-writing", "help-authoring-tool"],
    "publisher": "MadCap",
    "title": "Flare"
  },
  {
    "category": [
      "technical-writing",
      "structured-authoring",
      "help-authoring-tool",
      "coding-experience"
    ],
    "publisher": "oXygen",
    "title": "oXygen XML Editor"
  },
  {
    "category": ["technical-writing", "docs-as-code", "coding-experience"],
    "publisher": "Microsoft",
    "title": "VS Code"
  },
  {
    "category": ["content-management", "coding-experience"],
    "publisher": "Automattic",
    "title": "WordPress"
  },
  {
    "category": ["content-management", "coding-experience"],
    "publisher": "Drupal",
    "title": "Drupal CMS"
  },
  {
    "category": ["metrics", "coding-experience"],
    "publisher": "Microsoft",
    "title": "SQL Server"
  },
  {
    "category": ["metrics", "coding-experience"],
    "publisher": "IBM",
    "title": "Db2 database"
  },
  {
    "category": ["docs-as-code", "coding-experience", "technical-writing"],
    "publisher": "GitHub/Microsoft",
    "title": "GitHub/GitLab"
  },
  {
    "category": ["technical-writing"],
    "publisher": "SnagIt",
    "title": "SnagIt screen capture"
  },
  {
    "category": ["coding-experience"],
    "publisher": "Open-source",
    "title": "PlantUML diagramming language"
  },
  {
    "category": ["technical-writing", "coding-experience"],
    "publisher": "Open-source",
    "title": "Extensible Stylesheet Language Transformation (XSLT)"
  },
  {
    "category": ["technical-writing", "coding-experience"],
    "publisher": "Open-source",
    "title": "Cascading Stylesheets (CSS)"
  },
  {
    "category": ["technical-writing"],
    "publisher": "John Gruber/open-source",
    "title": "Markdown"
  },
    {
    "category": ["technical-writing", "coding-experience"],
    "publisher": "Open-source",
    "title": "XML"
  }
]

Being on this side of the equation makes it clear how much structuring your content helps your developers. It also helped me narrow my focus on skills, as well as tell a story across all of my content.

My progression included:

Accessibility

I used the WAVE browser plugin to test my pages and ensure they were accessible. My wife is a developer and accessibility advocate and as a technical communicator, I wanted my site to be accessible to everyone.

Screenshot of WAVE accessibility plugin results