Ed Marsh

Content Content Podcast: The people behind the content

Ed Marsh — Mon, 22 Jun 2026 00:00:00 GMT

Discuss technical communication, content strategy, mentorship, and podcasting!

Ed Marsh — Mon, 22 Jun 2026 00:00:00 GMT

LLMs

Ed Marsh — Mon, 22 Jun 2026 00:00:00 GMT

Blog

Ed Marsh — Mon, 15 Jun 2026 00:00:00 GMT

Creating website templates using AI

Ed Marsh — Fri, 15 May 2026 00:00:00 GMT

When converting my site to a static site generator (SSG), I learned they require templates to convert my Markdown files to HTML based on the associated template. Templates also enforce structure and allow dynamic content.

I didn’t know a thing about templating languages, so I turned to large language models (LLMs) to help me write code for the templates on my site. There are many templating languages, but I chose Nunjucks basically because it was the default for a lot of the Eleventy documentation. Nunjucks is based on Jinja.

What I learned about LLMs

LLMs can only do so much, and are often just plain wrong (known as hallucinations). What I learned is that if you want good answers, then you have to think through your logic. It’s your typical GIGO (garbage in, garbage out) cycle, so it’s helpful to write it down regardless of the language.

Over the course of my back-and-forth with the LLMs, understanding the logic I wanted helped me to accurately frame the question to the LLM. This made me think more and more about how to craft prompts, and how technical writers can educate regular folks how best to use AI.

On the plus side, the LLMs did things it would’ve taken me a lot more time to learn and do manually. Here are a few things that the LLMs helped me work through:

Continual content/metadata revision.
Repeatedly interating on templates.
Trying to modularize by abstracting templates in templates.
Sorting entries like podcast episodes in reverse order by appending | reverse
How to split arrays of items and display them using slices.

How to create a “shortcode” to programmatically display the current year:

eleventyConfig.addShortcode("year", () => `${new Date().getFullYear()}`);

Collections (essentially tags) and how to use them to group topics.

Gemini vs. Copilot

I pitted Google’s Gemini against GitHub Copilot. I prompted Gemini with:

I'm creating a web site using Eleventy, Nunjucks, Tailwind CSS, HTML, and Markdown. I'd like your help with a template for the homepage.

Here’s the response. Note the items in braces are part of the Nunjucks template language.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Eleventy Site</title>
    <link href="/styles/tailwind.css" rel="stylesheet">
</head>
<body class="bg-gray-100 text-gray-900 font-sans">
    <header class="bg-blue-600 text-white p-4 shadow-md">
        <h1 class="text-3xl font-bold">Welcome to My Site</h1>
    </header>

    <main class="container mx-auto mt-8 px-4">
        <section class="mb-8">
            <h2 class="text-2xl font-semibold">About</h2>
            <p class="mt-2">
                {% markdown %}
                Welcome to my website. Here you will find information about me and my projects.
                {% endmarkdown %}
            </p>
        </section>

        <section class="mb-8">
            <h2 class="text-2xl font-semibold">Latest Content</h2>
            <div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
               {% assign allItems = collections.all | sort_by: 'date', 'desc' %}
                {% for item in allItems | slice(0, 6) %}
                <div class="bg-white p-4 shadow-md">
                    <h3 class="text-xl font-semibold">{{ item.data.title }}</h3>
                    <p>{{ item.data.description }}</p>
                </div>
                {% endfor %}
            </div>
        </section>
    </main>

    <footer class="bg-gray-800 text-white p-4 mt-8">
        <p>&copy; 2025 My Eleventy Site</p>
    </footer>
</body>
</html>

Copilot said that the Gemini version was well-structured and accurate. Here’s the result:

The 2026 update

I’m writing most of this post a year after I drafted it. I fed the same prompt into the qwen3-coder-30b-a3b-instruct model that I’m running locally in LM Studio, and it output the following. It’s pretty obvious how advanced even locally running LLMs with a relatively small number of parameters have become in the past year. The 2026 version is far more detailed — and documented!

 <!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{ title }}</title>
    <meta name="description" content="{{ description }}">
    <link href="/styles.css" rel="stylesheet">
</head>
<body class="bg-gray-50 text-gray-900">
    <header class="bg-white shadow">
        <div class="container mx-auto px-4 py-6 flex justify-between items-center">
            <h1 class="text-2xl font-bold">{{ title }}</h1>
            <nav>
                <ul class="flex space-x-4">
                    <li><a href="/" class="hover:text-blue-600">Home</a></li>
                    <li><a href="/about" class="hover:text-blue-600">About</a></li>
                    <li><a href="/posts" class="hover:text-blue-600">Posts</a></li>
                </ul>
            </nav>
        </div>
    </header>

    <main class="container mx-auto px-4 py-8">
        <!-- Hero Section -->
        <section class="text-center mb-12">
            <h2 class="text-4xl font-bold mb-4">{{ title }}</h2>
            <p class="text-xl text-gray-600 max-w-2xl mx-auto">{{ description }}</p>
        </section>

        <!-- Featured Content -->
        <section class="mb-12">
            <h3 class="text-2xl font-semibold mb-6">Latest Posts</h3>
            <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
                {% for post in collections.posts | reverse %}
                <article class="bg-white rounded-lg shadow-md overflow-hidden">
                    <a href="{{ post.url }}">
                        <h4 class="text-xl font-semibold p-4 hover:text-blue-600">{{ post.data.title }}</h4>
                    </a>
                    <div class="p-4 text-gray-600">
                        {{ post.templateContent | slice(0, 150) }}...
                    </div>
                </article>
                {% endfor %}
            </div>
        </section>

        <!-- About Section -->
        <section class="bg-white rounded-lg shadow-md p-6 mb-8">
            <h3 class="text-2xl font-semibold mb-4">About This Site</h3>
            <p>This is a simple homepage built with Eleventy, Nunjucks, Tailwind CSS, HTML and Markdown.</p>
        </section>

        <!-- Newsletter Signup -->
        <section class="bg-blue-50 rounded-lg p-6">
            <h3 class="text-xl font-semibold mb-2">Stay Updated</h3>
            <p class="mb-4">Subscribe to get the latest posts delivered to your inbox.</p>
            <form class="flex flex-col sm:flex-row gap-2">
                <input type="email" placeholder="Your email address" class="flex-grow px-4 py-2 rounded border focus:outline-none focus:ring-2 focus:ring-blue-500">
                <button type="submit" class="bg-blue-600 text-white px-4 py-2 rounded hover:bg-blue-700">Subscribe</button>
            </form>
        </section>
    </main>

    <footer class="bg-gray-800 text-white py-8">
        <div class="container mx-auto px-4 text-center">
            <p>&copy; {{ "now" | date("YYYY") }} {{ title }}. All rights reserved.</p>
        </div>
    </footer>
</body>
</html>

Human widget 3592 with Sharon Burton

Ed Marsh — Sun, 08 Mar 2026 00:00:00 GMT

Sharon was the very first Content Content guest in 2015. She’s a content strategist, technical writing professor at the University of California Riverside, and editor of the book Women in Technical Communication: From typewriters to touchscreens, a history by the women who did the work. Sharon’s book is available at:

Call for writers for Sharon’s next book

If you know women engineers near retirement age or retired, help spread the word for the next book: Women in Engineering.

Credits

Intro voiceover by one of my best friends since high school, Corey Holtzberg at Coho Studios.
Intro music bed: Let’s Relax by VGM Mark H
- Music promoted by https://www.free-stock-music.com
- Creative Commons / Attribution-NoDerivs 3.0 Unported (CC BY-ND 3.0) https://creativecommons.org/licenses/by-nd/3.0/

Creating my portfolio website in a virtual environment

Ed Marsh — Sat, 07 Mar 2026 00:00:00 GMT

I’ve experimented with Linux for decades. I played around with Red Hat Linux in the early 2000s at my first tech writing job. I tried to understand OpenSUSE on my HP 2140 Netbook back in 2009 (I installed Ubuntu instead pretty quickly). I even gave a presentation about VMs back in 2010. So when I decided to rebuild my website, I knew I wanted to develop it in a Linux desktop virtual environment on a virtual machine (VM). Why?

I love Windows and always have, but I had concerns about trying to configure my bread-and-butter machine to work with things I wasn’t yet comfortable with. This compartmentalization let me break things and start over without interrupting my day-to-day.
Free! From the VMWare Workstation host to the operating system, the only thing it cost was some time and disk space (and it changed the way I work).
It allowed me to configure, test, and run static site generators (SSGs) like Hugo and Eleventy in the environments they’ll eventually run.
Not Apple. The only Apple product I’ve ever owned was an iPad 3 and I hated every minute of it.
It’s fast, and the environment is incredibly customizable.
It’s a pretty easy transition from Windows to Linux with a GUI. Most apps you’re familiar with just have a different name and a different UI.
For the development and writing tasks of my project, it just worked.
Press Pause on the VM and you’re done.

How to start using a VM

When I said some time, that wasn’t entirely accurate. There’s a learning curve to working with Linux. You need to install and configure development tools and frameworks by command line interface (CLI), like NodeJS, or an SSG. This isn’t really anything you’d do differently with any other operating system, but there are often Windows or Mac apps that will do the heavy lifting for you.

Once you get over that curve, you spend your time using cross-platform apps and technologies like VS Code, GitHub, and OpenOffice.

You do have to make some decisions, and test them, but some are actually fun:

Choosing a virtual machine (VM) host — I was surprised to learn VMWare Workstation was much quicker than VirtualBox, which I used for years.
Trying out “flavors” of Linux if you have the time and inclination. I tried distributions (distros) like Fedora and Ubuntu; due to my familiarity with Ubuntu and self-imposed deadlines, it won.
Then there are desktop environments like GNOME and Kubuntu. For me, the Ubuntu-based Mint Cinnamon just worked. I bought a laptop and installed Mint on it, which was incredibly painless to install and configure.
Each VM and distro I tested were straightforward in terms of setup and had lots of handholding, as well as pretty good documentation.

And then one day…

One day I opened my VM to find it no longer had internet connectivity. My host (Windows) computer had access, other VMs I was testing had connectivity, so something happened to my working version. An hour or so searching and the answer was… well, I’m not sure. It’s possible that it broke from an update, but I lost time trying to find the right magic commands. because it wasn’t something easily done through the GUI.

The good news is that if you do this in a VM, it’s far easier to recover without affecting your daily machine. I just started over with a new virtual machine. My code was in GitHub, so it made it much quicker to recover and keep working after I reinstalled, and had the added benefit of cleaning up my earlier mistakes.

My new daily driver

Fast-forward a year and Kubuntu is now my daily OS. Once you get over the learning curve, you’ll find Linux desktops are much more customizable than Windows.

I only boot into Windows to play motorsport games with a sim-racing rig. Everything else — including my favorite city-building game — runs great in Linux. I’ve even created my own Linux-based homelab.

It worked for me

Working in a virtual environment provided a teaching moment, separated work from daily life, and eventually led to a complete change in how I use my computer daily. I don’t always love the learning curve, but I have zero regrets in choosing to build my site this way.

When your content strategy goes wrong

Ed Marsh — Wed, 19 Nov 2025 00:00:00 GMT

A major part of my post-launch content strategy was releasing blog posts on a regular cadence to drive traffic. As I built my site, I documented the process through partially written Markdown files. I stored these blog post stubs in a DONT-DELETE branch in my Git repository. Not quite best practice, but also not unusual to those who have had to clean up obsolete branches.

When it came time to pull one out of that branch, I decided the content reuse piece was in pretty good shape. I updated it, published the post, and felt good about where I’d taken it. It followed an AI-related post that was widely viewed (surprise!). Not surprisingly, the AI post was a bigger draw than content reuse.

…Then I noticed I’d already used a large portion of it on my already-published site structure post. Ironically, my blog post about reusing content duplicated my own content.

Test case

Once I discovered the mistake a few days later, I left both up for a couple of weeks to see what happened (also to figure out what to do next). Either no one noticed or no one notified me. Based on my Google Analytics, it seems to be the former.

Lessons learned

I had a chance to fix things that no one noticed. I restructured and rewrote three posts to make for tighter, more focused topics, and linked across them to (hopefully) drive traffic.

The reality is that this is a luxury you don’t have when you publish professional content at scale. In a production environment with a team of writers, my error would probably be noticed in a content review by someone who’s familiar with existing body of content. But this relies on humans, which is why it’s important to have governance and automated quality checks in place.

On the plus side, I got another blog post out of it.

Content reviews

Ed Marsh — Thu, 25 Sep 2025 00:00:00 GMT

Use this free, two-page checklist to ensure your web presence and its content are working for your organization. Contact me if you want to learn more or take a deeper dive with a content audit!

Technical writing

Ed Marsh — Thu, 25 Sep 2025 00:00:00 GMT

Detective: Tracking down information across wikis, SharePoint, Confluence, legacy systems, and Subject Matter Experts (SMEs).
Librarian: Knowing what information is available, what information users actually need, and where to find it.
Translator: Tech writers interact with a bunch of folks with differing commands of the English language, as well as those whose priority or focus isn’t on the writing. We get it, we’re all busy. That’s where tech writers and editors come in.

Transforming technical communication for modern organizations

30+ years of experience means I’ve touched on all aspects of technical communication. My approach helps organizations not just create documentation, but build sustainable content ecosystems that drive user engagement and support business growth.

I’ve created:

API reference documentation
Cheat sheets
eLearning modules
Multimedia
Online help
PDF documentation
Podcasts
Printed manuals
Technical illustrations

Strategic content leadership

Transform complex technical information into clear, user-focused documentation.
Implement data-driven content strategies that align with business objectives.
Build and maintain robust content governance frameworks.
Design a scalable information architecture that grows with your organization.
Associate Fellow, Society for Technical Communication (STC).
Award-winning newsletter editor for STC NY Metro Chapter.
Award-winning designer and contributor of a company’s first full-color printed publication.

Podcasting

Ed Marsh — Thu, 25 Sep 2025 00:00:00 GMT

Podcasts are a terrifically friendly and informative way to get your message out. With over seven years of experience in podcasting, and numerous presentations about the value of podcasting, let’s consider this as part of your content strategy.

Examples

Created, hosted, scheduled, recorded, edited, produced, published, promoted, and reviewed metrics for the Content Content podcast, interviewing leaders in technical communication, information architecture, content strategy, and more.
Host of LavaCon content strategy conference podcast.
Guest:

Metrics and data

Ed Marsh — Thu, 25 Sep 2025 00:00:00 GMT

Measuring how your content performs can help your organization:

Plan
Ensure the content you create is relevant
Address highly used topics
Identify gaps
Report

Examples

Set up custom Elastic Kibana dashboards to monitor content quality and traffic.
Designed and wrote division-wide email newsletter blasts highlighting metrics, featured content, and relevant content for each quarterly reporting period. Metrics indicated these blasts drove traffic to featured topics.
Initiated custom quarterly reports that displayed metrics analysis for senior management.
Wrote SQL queries to analyze actual performance of a legacy help system, which informed migration to a new platform.

Information architecture

Ed Marsh — Thu, 25 Sep 2025 00:00:00 GMT

The way you present and organize your content says a lot to your clients and customers. Giving structure to your organization’s content ensures:

Your reputation is bolstered by high-quality content.
Consistency across every piece of content and channel.
Programmatic ingestion and manipulation.
Effective SEO.
A consistent experience to your users and staff.
People quickly get the answers they need to move on with their day.

Examples

Re-architected a 1200-topic, 10-year-old Adobe RoboHelp HTML system based almost exclusively on FAQs. Using a data-driven approach, I reduced topics by 50% and increased traffic to the remaining topics.
Developed and implemented a unique publishing workflow leveraging DITA XML and XSLT to use Confluence as a Content Management System (CMS).

Content strategy

Ed Marsh — Thu, 25 Sep 2025 00:00:00 GMT

Let’s be honest. Most organizations’ content is scattered across Confluence pages, SharePoint, your company’s intranet, hundreds of repositories, help systems which may or may not be current, knowledge management systems, Word documents, and more.

Content strategy means the right content in the right format at the right time in the right place. Do you really want to “throw AI” at it without understanding the complexity and the true costs?

The best place to start is with a content audit. I love content audits. Let me help you and show you how to:

Understand what content assets you have, where they are, and the formats they’re in.
Use metrics to guide your strategy.
Define a common language through a style guide.
Define structure through information architecture.
Govern and maintain your content.

Governance

Content without governance is an organizational nightmare: unsustainable, and impossible to maintain.

The content your organization generates needs a goal, organization, style, and governance. Without someone setting content standards and monitoring its performance:

Your content becomes disorganized and strewn across multiple platforms.
Content duplication makes it impossible for your employees, clients, and users to find the single source of truth.
Productivity declines because your employees are searching multiple places.

Here’s a free, two-page checklist to ensure your site’s content is best portraying your company’s best side. Contact me if you want to learn more!

Examples

Managed and coordinated product content strategy for 35+ products with stakeholders including senior management.
Ensured content quality by implementing style guide and documentation linter with custom business rules that improved consistency across all products.
Identified user and organizational knowledge needs by conducting user research in formal interviews, informal conversations, focus groups, analytics research, and support ticket analysis.

Community building

Ed Marsh — Thu, 25 Sep 2025 00:00:00 GMT

I have a history of finding those people and encouraging them to be champions for high-quality content that’s an asset to your firm.

Stakeholder management

I have a long track record successfully interacting with:

Product managers
Business analysts
Senior management
Cross-divisional leadership
The Executive Office
Internal Audit
Support teams
End users
Developers

How I’ve built community

Held quarterly “content champions” meetings with interested stakeholders to get their feedback on how our content and site are performing, and workshop upcoming content initiatives.
Started a regular “content creators catchup” that brought cross-divisional tech writers, UXers, and others involved with content across the firm together to share and learn.
Created custom monthly metric emails to let stakeholders know how their content is performing, and where there may be gaps or opportunities.
Spoken at user groups and conferences.
Created a pioneering podcast to give back to the technical writing community.

Coding experience

Ed Marsh — Thu, 25 Sep 2025 00:00:00 GMT

Here’s how I’ve used code to solve content problems:

Created my first website in the 1990s.
Wrote SQL queries to analyze hidden user metrics in a legacy help system.
Converted a 1500-topic Adobe RoboHelp project to DITA XML.
Developed custom XSLT transforms for DITA-to-HTML conversion.
Built a unique publishing platform using Atlassian Confluence as a CMS with a custom front end.
Created a Python script to help subject matter experts (SMEs) auto-fill homepage metadata.
Automated repetitive team tasks through custom scripting.
Designed and built contentcontent.info — a decade-long technical content aggregator — using Drupal CMS.
Helped establish the Drupal CMS Northern NJ user group as a founding member.
Built edmarsh.com from scratch using WordPress in 2008.
Transformed edmarsh.com to run on a static site generator in 2025.
Defined Jira user story guidelines that were adopted division-wide within three months of onboarding.
Wrote Jira user stories and epics following Gherkin language principles.
Worked with Kanban and story boards.

AI usage

Ed Marsh — Thu, 25 Sep 2025 00:00:00 GMT

Here’s how I’ve used AI:

Created custom prompts for things like my home network, resume reviews, technical writer assistant, and more.
Created a Python script that prompted users to fill in the required fields for the homepage template.
Ran multiple LLMs locally through LM Studio (mostly from the Qwen3 family).
Replaced GitHub Copilot in VS Code with local LLMs using the Cline extension.
Developed my portfolio website using Google Bard/Gemini, Claude, GitHub Copilot, and local LLMs.
Locally hosted SearXNG anonymous search engine in a Docker container and added it as an MCP server so local LLMs can access the internet.

Ed Marsh creates content and community

Ed Marsh — Thu, 25 Sep 2025 00:00:00 GMT

Moving from WordPress to a static site generator

Ed Marsh — Thu, 25 Sep 2025 00:00:00 GMT

Ed Marsh: technical communicator, content strategist, podcaster, mentor

Ed Marsh — Thu, 25 Sep 2025 00:00:00 GMT

I’m a proud New Jersey native, and I’m passionate about:

Proper punctuation (especially the em dash —, semicolon, and ellipsis…).
The Oxford comma.
Craft beer (former homebrewer).
Making restaurant-quality food at home with local ingredients.
IndyCar racing.

Career journey

My career started in New York City’s software industry at Information Builders (now part of Tibco) in 1994. I learned how to be a technical writer as part of a large documentation team.

My web journey started in the mid-1990s with my first website (archived link).

After a stint as a solo technical writer for a financial services SaaS provider — where I spent time on a trading floor and in data centers — I progressed to Goldman Sachs. Over 13 years, I worked in two divisions on Wall Street, creating both user- and developer-facing content. Working in small, medium, and enterprise environments taught me crucial lessons about:

Cross-functional collaboration.
Risk management.
Governance.
Content strategy at scale.
Managing projects and subject matter experts.

Here’s how I’ve continually evolved throughout my adult life:

Learning how to be a technical communicator.
Learning how to teach music to middle- and high-school students.
Learning how to write music.
Developing content strategy.
Implementing governance.
Managing projects.
Public speaking.
Creating my own podcast.

A love of learning and teaching

As a former high school drumline instructor, my goal was to get young drummers playing and sounding like one through teamwork and structure — which helps me bring a structured approach to content.

I’ve mentored dozens of people:

Former students.
Colleagues.
Children of former colleagues.
Numerous people on the ADPlist platform.

My band leadership experience includes:

Teaching high school marching band part-time (with a full-time job) for 14 years, including six as director.
Representing the state of New Jersey in Washington DC’s National July 4th Parade.
Co-founding a percussion ensemble called Cacophony, writing original scores.
Creating and maintaining the band’s website starting in 1996 — which led to the band performing in an Ikea advertisement.
Receiving recognition from School Band and Orchestra magazine as one of “50 Directors Who Make a Difference”, representing New Jersey in 2006.

Asking AI to write documentation

Ed Marsh — Tue, 23 Sep 2025 00:00:00 GMT

The answer for coders is not yet. For those on the more creative end, including technical writers, it’s a bit more grey.

I’ve always dabbled in code, but had difficulty expressing the logic in my head in code. So I asked AI to do a tech writer’s job and document the code for my site.

My first forays into large language models were with Google Gemini (née Bard). I asked how to write code for automation tasks in Windows Powershell and Python. Fast-forward a year or two, and GitHub Copilot is baked into VS Code.

AI documentation output

I asked GitHub Copilot (and other AI LLMs) to do my job by documenting my codebase, write summaries, and even read through my own content. My prompt was think like a technical writer and create a markdown file that documents this site.

This is a good example of what AI can do for you, but also where humans are invaluable. A large language model (LLM) can write a code sample, but can’t tell if it displays correctly.

Because the output includes a mix of Markdown, template code, and HTML, it’s nearly impossible to display correctly in a codeblock. I created a separate branch and excluded these from collections using the eleventyExcludeFromCollections: true parameter in my front matter, which means it won’t appear as a page on the site.

Original output for the first draft of the site.

Version 2

Most recent version

If you look at the output, it’s pretty impressive that AI can get to this level of granularity. But the results are only high-level overviews, and parts are not entirely correct — partially as a result of my lack of coding experience. For example, in the original the Featured content section is technically correct. However, at the time I asked the question it wasn’t working.

There’s still a need for a person to review and verify generated output, particularly for liability purposes. Attorneys won’t be happy if their organization is sued for incorrect documentation that’s written by AI.

The llms.txt file

I read about the llms.txt file, which gave me exactly the distraction I needed from writing content that I’d been putting off.

I ran three different online llms.txt generators against both my current production and my development site. These generators request your website’s URL, crawl it, and create an llms.txt Markdown file for you.

What I took away is how my site is interpreted by people, bots, and generative AI. It’s interesting to see how the generators return similar but not identical results from what’s essentially the same content:

A podcast episode discussing project management and technical communication in the hardware industry with Viqui Dill.
Discussing project management and technical communication with Viqui Dill in a podcast format.
Discussing the intersection of project management and technical communication through Viqui Dill’s insights and experiences.

Conclusions

There’s plenty to learn from this output, especially because it’s only going to get better. I think there’s opportunity for technical communicators to improve and verify AI-generated documentation. There’s also huge potential for tech writers to use AI to describe their codebase, generate code samples, and translate content into useful info.

I’m not ~~proud~~ shocked by how much I relied on a chatbot to program this website, but it helped me deliver (toward the end of this project I learned this is called vibe-coding). I’m not a developer, and my goal wasn’t to become one, so using AI allowed me to (eventually) focus on the content I wanted to focus on. It did make me appreciate specialized development roles, because no one can do it all, even with AI.

The why: Behind my SSG conversion project

Ed Marsh — Sat, 01 Mar 2025 00:00:00 GMT

I started this project as a strategic effort to create a portfolio highlighting my technical writing and content strategy skills. I didn’t have any recent writing samples to share with potential employers or clients due to intellectual property (IP) laws, which I take seriously. The public-facing samples I did have were woefully out-of-date, as was my WordPress site. I didn’t realize just how out-of-date the site was until I got deep into this project. I needed to redesign not only the site, but its content.

This was a rare greenfield opportunity to:

Audit a lifetime’s worth of content, dating back to LiveJournal blogs.
Get rid of cruft.
Reduce the costs of hosting and maintaining my own site.
Understand how content is programmatically consumed and displayed to users.
Learn some new skills without a lot of deadline pressure.
Give back and explain to other technical communicators what building a modern web site from scratch entails.

Background

I knew from an early age I’d be involved in writing in some way. I interviewed friends on cassette in elementary school. I had my own 'zine. But since the days of the Commodore VIC-20, I’ve always been curious about and dabbled in software development. I started building websites in 1996, which led me to a Drupal site, and also a WordPress personal site I built in 2008:

That site and its scope expanded when I started my podcast in 2015:

When I decided to take this project on, getting hands-on appealed to me.

Technical goals

Update a 10-year-old design.
Retire a complex WordPress site that didn’t get much traffic and needed maintenance.
“Quickly” revamp my website to increase my chances at getting hired.
Add value by developing with SSGs, which isn’t a skill a lot of technical writers have. SSGs — like Eleventy that I chose — display the content that technical writers create.
Learn newer technologies such as Nunjucks templating, that ended up leveraging old tech I’m familiar with like HTML and CSS.

Content goals

Generate a steady stream of content to drive traffic and feature as writing samples.
Give back to the technical writing community by documenting the process of building static site implementation process.
Review all the content on my site and see if it’s promoting my career in the best light.
Decide whether to archive old content, like those very early blog posts.
Understand how to structure content not only for SSGs, but other programmatic use.
Enjoy writing again.
Do something for me.

Cost savings goals

My web host (mddhosting) is great and worth the cost while I was actively updating the site. I no longer needed the complexity and related costs of it, so my goals were to reduce my financial and labor costs:

Minimize the overhead of maintaining a content management system. I no longer needed the complexity of a self-managed WordPress site. I hadn’t blogged in some time, and my podcast has been on hiatus since 2022. Maintenance included:
- Keeping up with plugin updates.
- WordPress updates.
- Processing the hundreds of spam comments that came through every day.
Reduce hosting costs. SSGs don’t require heavy infrastructure such as a database, so they can be hosted in places that WordPress sites can’t. This gave me flexibility to move to a zero- or low-cost host. That doesn’t mean there are zero costs to hosting the site:
- My existing site host was also my mail server, so I had to find and set up my own mail hosting. To add to the frustration, my first choice was too difficult to set up. So far, Zoho Mail has been great.
- Upgrading my podcast hosting. My podcast archive puts me at the limit of free disk space and bandwidth on GitHub, so I had to offload that to a paid service. The upside to this is I get metrics I wouldn’t if they were self-hosted.
- Downsizing from a web host I’d undergrown meant I could re-allocate those resources.

While this solution is cheaper in long-term costs, there was considerable investment in upskilling, setting up infrastructure, creating templates, and making mistakes. I took on mail server costs and administration (which so far has been minimal).

Creating reusable content for static site generators (SSGs)

Ed Marsh — Sun, 23 Feb 2025 00:00:00 GMT

What is reusable content?

In a structured authoring environment, such as those that use Darwin Information Typing Architecture (DITA), an XML-based authoring language, you can set up content reuse, or snippets. Instead of copying and pasting sections into different files, you create a file that contains that small piece of content. You reference that file where it’s needed, like an include or import file.

Some unstructured syntaxes and SSGs have their own implementations of reuse. However, this becomes an education and enforcement issue if you have a wide variety of contributors such as developers, product managers, subject matter experts, and technical writers. This also exposes your business to vendor lock-in: once you have the toolset implemented, it’s hard to move away from it, especially when you come to rely on features other tools don’t have.

Metadata for content reuse

Copy-pasted content across pages is a maintenance nightmare. Someone has to remember to update it, and also all the places of the pasted content. With this in mind, I wanted to use metadata as much as possible for reuse and programmatic data access.

You can use metadata (also referred to as front matter or frontmatter) to define page titles, keywords, and leverage built-in categories and tags.

The real power comes by adding custom metadata: highly structured content that expands the possibilities of the template engine and site generator. For example, I used the description field for the first sentence across the site. This allowed me to programmatically display the description on cards and each blog post, and let me style descriptions separately from everything else. It also enforces structure and allows writers and contributors to just write, since all of the logic is handled programmatically.

Most metadata fits a key-value pair format. Here’s what a metadata block looks like in YAML format:

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

Here’s what each metadata entry does:

Fieldname	Purpose
`title`	Page title that displays on cards, grids, details pages, and browser tabs. Note that in this instance, I had to wrap the title in single quotes as there is a colon in it; this would break the page otherwise.
`description`	The first paragraph of the post.
`FontAwesomeIcon`	Specifies the Font Awesome icon to display on the homepage, grid pages, and breadcrumbs.
`featured`	Displays the page on a card on the homepage.
`featuredOrder`	Sets the order in which the card displays on the homepage.

Here’s an example of how this content works programmatically. This code generates cards that references the metadata fields:


{%- macro gridItem(item) -%}
    <div class="bg-whitish p-4">
        <h3 aria-labelledby="{{ item.data.title |slugify }}">
            {% if item.data.FontAwesomeIcon %}
                <span class="fa-{{ item.data.FontAwesomeIcon }} text-2xl text-medium-blue"></span>
            {% endif %}
            {% if item.data.cover %}
                <img src="/assets/images/{{ item.data.cover }}" 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>
{% endmacro %}

Here’s what two cards look like side-by-side:

Auto-generated, context-sensitive links

The content stategy for my skills pages was to display the relevant tools and presentations for each skill. These started as bulleted lists, but it quickly became obvious that copying and pasting relevant bullets on each page wasn’t sustainable.

Since there’s no database behind a static site generator, I created two json files that enforce structure while remaining expandable. The first file contained information about my presentations, webinars, and guest appearances. This json file contained titles, year (or years) of the item, a relevant link, the category or categories for each, the location or event venue, and type (webinar, in-person, panel discussion, podcast guest or host, etc.). Here’s an example:

{
    "title": "So, you want to be a technical writer?",
    "year": "2024",
    "link": "https://www.brighttalk.com/webcast/9273/608187",
    "category": ["technical-writing", "metrics", "content-strategy", "marketing"],
    "venue": "Content Wrangler webcast",
    "type": "webinar"
},

The second JSON file listed the tools I’ve used over my career, along with their publisher, product name, and relevant site categories. I asked AI to help me with this, because while the structure of a JSON file is relatively easy to follow, formatting is very important. Here’s my prompt:

Think like a programmer. i want a JSON file with the following structure:
- Skill title
  - description
  - Tools used
  - Technologies used

  tools and technologies will need to be pulled into several templates, so explain how i can assign them to multiple skills

Here’s an example of the result:

{
    "category": [
        "technical-writing",
        "help-authoring-tool"
    ],
    "publisher": "MadCap",
    "title": "Flare"
}

Then I created templates that render these structures, achieving a single source of truth that adapts to different display contexts. Here’s part of the template renders presentation data:

{% if presentations %}
<h2>Related work</h2>
{% set presentationsList = isPublicSpeakingPage and presentations or filteredPresentations %}
{% for presentation in presentationsList | sort(false, false, 'year') | reverse %}
    <div class="presentation mb-4">
        <h3 class="font-normal text-[1rem]">
            {# Check if presentation has a link #}
            {% if presentation.link %}
                {{ presentation.type | capitalize }}:
                <a href="{{ presentation.link }}" class="hover:text-success-600 italic">
                    {{ presentation.title }}
                </a>
            {% else %}
                {{ presentation.title }}
            {% endif %}
        </h3>
        <p class="text-sm mt-0 jet-600">
            {{ presentation.venue }}, {{ presentation.year }}
        </p>
    </div>
{% endfor %}
{% endif %}

I can now programmatically populate my skills pages with the relevant presentations and tools:

The how: Building the site structure

Ed Marsh — Sun, 02 Feb 2025 00:00:00 GMT

When you start with a decade-old information architecture that evolved to include podcasts, it shouldn’t be surprising that very few parts of that structure end up in a new site.

I quickly decided it wasn’t worth maintaining my old personal and professional blog posts. Most were outdated and not helpful to the portfolio I wanted the site to be.

Content types

I designed three main content types (page types):

Homepage, which included an intro, headshot, and galleries of the four most important, or recent, items that have been updated in three categories: podcasts, skills, and blog posts.
Grid pages that are gallery pages with cards for each skill, blog post, and podcast episode.
Details pages for each of the categories:
- Blog posts.
- Podcast episodes, including show notes and an episode player.
- More information about each of my skills, the relevant tools used, and any relation presentations or publications I’ve created.

Separating content from presentation

Making this actually happen involved a lot of experimenting. 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.

Once I grasped how to use content programmatically, it opened my eyes to how much reusable structures like metadata make a difference in how content is sorted, filtered, and displayed.

Taking an active development role made it clear to me how structuring your content helps your developers and your readers. Abstracting my content taught me:

Using metadata reduces input errors.
You can restrict what’s entered via pipelines and/or linters.
It makes it easier for people to contribute.
Sites can have a consistent voice and experience.
Your content is portable and easier to publish across multiple channels.

Accessibility

My wife is a developer and accessibility advocate. As a technical communicator, I wanted my site to be accessible to everyone. I was also able to programmatically use my metadata to populate <alt> tags. I used the WAVE browser plugin to test my pages and ensure they were accessible.

The what: Creating the content strategy for my site

Ed Marsh — Sat, 01 Feb 2025 00:00:00 GMT

Determining personas

The first question of technical writing is who is the user? The users you identify inform and guide your content strategy. In my case, my users include:

Potential employers.
Technical writers — both experienced and new.
Listeners (and potential listeners) of my podcast.
Those who want to learn about static site generators (SSGs) and/or docs-as-code.

Content goals

Highlight my skills to attract employers, and also as a thought experiment — what do I do with content strategy?
Document my migration experience from WordPress to a static site generator through a series of blog posts .
Highlight my podcast, as the old site really didn’t. I’m considering reviving the podcast so this was a priority.
Get rid of legacy content.
Ensure the site is accessible.

Blog release strategy

My strategy for documenting the conversion from WordPress to a static site generator (SSG) included:

Write 10-20 blog posts about the process, including:
- Migration
- Strategy
- Infrastructure
- Build-out
- Frustrations
- Development
- Content creation and revision processes
- Takeaways
Write four solid blog posts for the rollout.
Put that content out on a regular cadence to keep content fresh and drive continuous engagement.
Inspire tech writers to get more technical.
Understand and explain how content is consumed programmatically.
Show recruiters and employers that I was actively updating my site.

Ed Marsh creates content and community. What can he do for you?

Ed Marsh — Mon, 20 Jan 2025 00:00:00 GMT

The where: Working with a static site generator

Ed Marsh — Sun, 12 Jan 2025 00:00:00 GMT

When rebuilding my site, it made sense to use an SSG because it’s fast, self-contained, and relevant to what we do as technical communicators. The WordPress site I had for over a decade not longer served my purpose—both technologically and maintenance. The WordPress world also evolved too far for my limited PHP skills from a decade ago to ‘just tweak’. I no longer needed the WordPress complexity, infrastructure, features, and plugins that require maintenance. Using an SSG also fit my cost reduction goal.

The good news is there are a lot of static site generators to choose from, and that they all work similarly. The bad news is there are a lot of static site generators to choose from, and that they all work similarly. Once you learn the basic principles, it’s easier to figure out the nuances of each SSG and decide which is best for you.

Working with SSGs is not a plug and play experience. In a prior role, our output went through a heavily customized version of Gatsby. I wasn’t hands-on with it because we needed a team of developers to support it.

My SSG requirements

These were my requirements when choosing an SSG:

As plug-and-play as possible (in retrospect, ha!). I can play with HTML, CSS, and configuration and template files, but I don’t have a dev team behind me. Nor did I have time to learn modern JavaScript or Typescript.
Well-supported.
Quick time to market — I needed to quickly build out the site to be relevant to my job search.

The learning process

The important part to understand is that the SSG is just a generator. There are parameters and configuration, but what SSGs do is display the content you create through templates. The key takeaway was making sure to structure my content, regardless of the tools.

I had time, so I watched videos, read tutorials and blogs, looked up the pros and cons of templating approaches, and the SSG choice itself. I started to learn with the Hugo SSG. Eventually I moved to Eleventy (11ty). Why? Not surprisingly, a lack of documentation.

Eleventy’s docs aren’t much better, but its infrastructure is more open. Since I didn’t know anything about Eleventy, I stayed with its default Nunjucks templating language, which ultimately renders the HTML in your output. It’s based on the Liquid templating language so there was a lot of history and documentation to refer to. Amusingly, I found during the process that Tom Johnson referenced Liquid in our podcast together almost 10 years ago.

Lessons learned

When you decide to build a website from scratch with an SSG, you’re building it from scratch. Every SSG has starter themes and frameworks, but at that stage of the process, I didn’t understand enough about how SSGs worked to know how to properly use those themes. I also had the time and inclination to learn some new tech, so I decided to play every role of developing a website to help me appreciate how content is programmatically consumed.

I started building the site during the winter holiday downtime. It took me about three weeks to start “getting” how it all works. Does that mean it came quickly and easily? No. There were many “why isn’t this thing that’s supposed to work not working?” moments. Once I realized this is part of the process, it made it easier for me to look at this as a learning experience (if only it were that easy…).

Sink and swim situation with Ann Rockley

Ed Marsh — Fri, 28 Jan 2022 00:00:00 GMT

Mentioned during this episode

A really fancy webform with Patrick Bosek

Ed Marsh — Mon, 27 Sep 2021 00:00:00 GMT

This episode was recorded before Patrick’s company changed its name to Heretto.

Mentioned during this episode

Clarity over consistency with MJ Babic

Ed Marsh — Tue, 08 Jun 2021 00:00:00 GMT

MJ’s had a diverse career, from marketing, feature articles, science journals, and tech writing. But her plan is “helping people complete their tasks with digital products”, and to “bring good writing to whatever corner I’m working in at the moment”.

Mentioned during this episode

Not acting like slow computers with Rahel Bailie

Ed Marsh — Wed, 14 Apr 2021 00:00:00 GMT

Her Content Strategy book with Noz Urbina remains one of Ed’s most highlighted (highlit?) reads. We discuss Content Operations (ContentOps or DocOps), introducing efficiency, and more. I hope you laugh as much as we did.

Mentioned during this episode

All the things in my Venn diagram with Alisa Bonsignore

Ed Marsh — Wed, 30 Sep 2020 00:00:00 GMT

Mentioned during this episode

Four engineers and an English major with Michael Miller

Ed Marsh — Thu, 23 Jul 2020 00:00:00 GMT

Mentioned during this episode

Value-oriented outcomes with Sara Feldman

Ed Marsh — Tue, 19 May 2020 00:00:00 GMT

Mentioned during this episode

1,000 or 100,000 meetings with Noz Urbina

Ed Marsh — Tue, 07 Apr 2020 00:00:00 GMT

Mentioned during this episode

Softquad
XMetaL
Mekon
Congility
OmniX conference - get €50 off with the code 50urbi
Carrie Hane
Content Strategy: Connecting the dots between business, brand, and benefits

Fluffy experience with Hannah Kirk

Ed Marsh — Tue, 11 Feb 2020 00:00:00 GMT

Mentioned during this episode

I like the Ms with Phylise Banner

Ed Marsh — Fri, 27 Dec 2019 00:00:00 GMT

Mentioned during this episode

We're gonna do this together with Viqui Dill

Ed Marsh — Wed, 26 Jun 2019 00:00:00 GMT

Viqui is also an accomplished ‘bad-ass bass player’ and a self-proclaimed techcomm evangelist.

Mentioned during this episode

XML is a four-letter word with Alan J. Porter

Ed Marsh — Thu, 14 Mar 2019 00:00:00 GMT

Alan is also an accomplished author and critic of comics, pop culture, sci-fi, and more.

Mentioned during this episode

I have issues with slide decks with Scott Abel

Ed Marsh — Tue, 20 Nov 2018 00:00:00 GMT

Mentioned during this episode

Experiences have to be assembled with Cruce Saunders

Ed Marsh — Fri, 14 Sep 2018 00:00:00 GMT

Mentioned during this episode

Holding somebody else's place with Sean Heckman

Ed Marsh — Fri, 20 Apr 2018 00:00:00 GMT

Learn what it’s like to drive across the USA for 30+ days interviewing racing legends, while running a content creation business that caters to small businesses. Find out why Sean calls a “sport with science, technology, and a lot of nonsense” his home.

I’ve never met Sean, and he was as curious about me as I was about him. Sean says he’s not a journalist, but he is. He gets people to talk, listens to their stories, and responds to them. He also has an immensely dry sense of humor. I literally had to stop dozens of times while editing this podcast to stop laughing. Give this a listen.

Mentioned during this episode

I can eat glass with Keith Schengili-Roberts

Ed Marsh — Tue, 13 Mar 2018 00:00:00 GMT

Mentioned during this episode

Installation is not a user task with Andrea Ames

Ed Marsh — Tue, 23 Jan 2018 00:00:00 GMT

Andrea is the CEO of Idyll Point Group, after a long stint in content strategy and content experience strategy at IBM.

Mentioned during this episode

<h3>Enterprise Marketer podcasts</h3>

The price is right with Tim Esposito

Ed Marsh — Thu, 30 Nov 2017 00:00:00 GMT

Mentioned during this episode

Same mess different tools with Liz Fraley

Ed Marsh — Tue, 12 Sep 2017 00:00:00 GMT

Mentioned during this episode

Emo analytics with Allie Proff

Ed Marsh — Wed, 26 Jul 2017 00:00:00 GMT

Mentioned during this episode

Be like Thomas Pynchon with Pawel Kowaluk

Ed Marsh — Tue, 27 Jun 2017 00:00:00 GMT

After recording, we became aware that Pawel left the Soap! Conference team after one year. To further clarify, Pawel did not have a role in the formation of MeetContent, though he is an active member of the community. Content Content regrets any confusion or offense to those involved.

Mentioned during this episode

Users or people with Jack Molisani

Ed Marsh — Mon, 24 Apr 2017 00:00:00 GMT

Mentioned during this episode

Napoleons and Shakespeares with Teresa Meek

Ed Marsh — Tue, 14 Feb 2017 00:00:00 GMT

Mentioned during this episode

It's OK to pause with Alyssa Fox

Ed Marsh — Tue, 15 Nov 2016 00:00:00 GMT

We also discuss managing people “fairly, not equally”, why content strategy is difficult, multinational technical communication teams, fashion, and more.

Mentioned during this episode

Local needs of content with Bill Swallow

Ed Marsh — Fri, 30 Sep 2016 00:00:00 GMT

Released on International Podcast Day!

Mentioned during this episode

Off the wall presentations with Ben Woelk

Ed Marsh — Thu, 01 Sep 2016 00:00:00 GMT

Mentioned during this episode

Single source of the truth with Bernard Aschwanden

Ed Marsh — Tue, 26 Jul 2016 00:00:00 GMT

Mentioned during this episode

Complimentary sandwich with Todd DeLuca

Ed Marsh — Fri, 13 May 2016 00:00:00 GMT

Mentioned during this super-sized episode

Fairly random events with Sarah O'Keefe

Ed Marsh — Fri, 11 Mar 2016 00:00:00 GMT

Mentioned during this episode

Curious about content with David Dylan Thomas

Ed Marsh — Tue, 19 Jan 2016 00:00:00 GMT

Mentioned during this episode

Where's my Flare with Dr. Carlos Evia

Ed Marsh — Tue, 27 Oct 2015 00:00:00 GMT

Carlos is the Director of Professional and Technical Writing at Virginia Tech, is on the Lightweight DITA Technical Committee, and is an advocate for using multimedia with DITA.

Mentioned during this episode

Undefinable Me with Marcia Riefer Johnston

Ed Marsh — Wed, 19 Aug 2015 00:00:00 GMT

Mentioned during this episode

Undefinable Me: The Story of a 13-Year-Old Girl from the Inner City Who Codes
Keila Banks’ inspiring 10-minute OSCON keynote
Malaphors (“Unintentional blended idioms and phrases—It’s the cream of the cake!” by David Hatfield, the Malaphor King)
What Is Intelligent Content? (includes links to my six-pack of articles delving into each element of Ann Rockley’s classic definition)
Writing.Rocks (Marcia’s blog, where you can play the weekly concise-writing game Tighten This!)
Word Up! on Amazon*
You Can Say That Again on Amazon
Content Content podcast episode 1 with Sharon Burton
Scott Abel
The Velveteen Rabbit
Ann Rockley
Managing Enterprise Content: A Unified Strategy by Ann Rockley and Charles Cooper
Techwhirl.com - Connie Giordano and Al Martine
Information Development World
Lavacon conference
STC - Philly Metro chapter
Content Marketing Institute
Joe Pulizzi
Robert Rose
Content Content podcast episode 3 with Danielle Villegas
Dair Communications
Techcommgeekmom

Ed Marsh

Content Content Podcast: The people behind the content

Discuss technical communication, content strategy, mentorship, and podcasting!

LLMs

Blog

Creating website templates using AI

Human widget 3592 with Sharon Burton

Creating my portfolio website in a virtual environment

When your content strategy goes wrong

Content reviews

Technical writing

Podcasting

Metrics and data

Information architecture

Content strategy

Community building

Coding experience

AI usage

Ed Marsh creates content and community

Moving from WordPress to a static site generator

Ed Marsh: technical communicator, content strategist, podcaster, mentor

Asking AI to write documentation

The why: Behind my SSG conversion project

Creating reusable content for static site generators (SSGs)

The how: Building the site structure

The what: Creating the content strategy for my site

Ed Marsh creates content and community. What can he do for you?

The where: Working with a static site generator

Sink and swim situation with Ann Rockley

A really fancy webform with Patrick Bosek

Clarity over consistency with MJ Babic

Not acting like slow computers with Rahel Bailie

All the things in my Venn diagram with Alisa Bonsignore

Four engineers and an English major with Michael Miller

Value-oriented outcomes with Sara Feldman

1,000 or 100,000 meetings with Noz Urbina

Fluffy experience with Hannah Kirk

I like the Ms with Phylise Banner

We're gonna do this together with Viqui Dill

XML is a four-letter word with Alan J. Porter

I have issues with slide decks with Scott Abel

Experiences have to be assembled with Cruce Saunders

Holding somebody else's place with Sean Heckman

I can eat glass with Keith Schengili-Roberts

Installation is not a user task with Andrea Ames

The price is right with Tim Esposito

Same mess different tools with Liz Fraley

Emo analytics with Allie Proff

Be like Thomas Pynchon with Pawel Kowaluk

Users or people with Jack Molisani

Napoleons and Shakespeares with Teresa Meek

It's OK to pause with Alyssa Fox

Local needs of content with Bill Swallow

Off the wall presentations with Ben Woelk

Single source of the truth with Bernard Aschwanden

Complimentary sandwich with Todd DeLuca

Fairly random events with Sarah O'Keefe

Curious about content with David Dylan Thomas

Where's my Flare with Dr. Carlos Evia

Undefinable Me with Marcia Riefer Johnston

Curse of knowledge with Tom Johnson

Fire fingers with Danielle Villegas

Time as a Tool with Alan Houser

Offices without tarantulas with Sharon Burton