Keeping Foundation Roster Help Articles in Step with the Product

Most software help centers drift. A feature changes, the help article doesn’t, and a few weeks later someone follows the instructions and finds a button that has moved or a screen that looks nothing like the picture. Nobody meant for that to happen. The help content just lived somewhere else, was updated by hand, and went live whenever someone remembered to publish it.

I wanted the Foundation Roster Knowledge Base to work differently. A center owner reading how to take attendance should see the screen they’ll actually find when they sign in, and the article should never describe a feature they can’t use yet.

So I stopped treating help content as a separate project. The articles and their screenshots are written and generated in the same place as the product’s code, and a small amount of automation publishes them to the website once the matching release is live. This post walks through how that works, for readers who like to know how things are built.

Why help content goes stale

When I looked at why documentation falls behind, it came down to three gaps:

1. The help text lives apart from the change. Feature changes happen in the code, not in a website editor. Updating the article becomes a second task, and second tasks slip.
2. Screenshots are made by hand. Someone has to sign in to an account with realistic data, get the screen into the right state, crop it, and upload it. That’s tedious enough that screenshots rarely get re-taken. And the accounts with the most realistic data belong to real customers, whose information should never appear on a public page.
3. Publishing isn’t tied to releases. An article goes live when I click publish, which can be before the feature ships or long after.

Each part of the approach closes one of those gaps.

The big picture

The product code, the help articles, and the scripts that capture screenshots all live in one place. The marketing website is a separate project that handles layout, navigation, and design, and receives the help content from the product side. Content only ever flows one way, from the product to the site.

Help articles live next to the code

Every Knowledge Base article is a plain text file (Markdown, with a few lines of metadata at the top such as its title, category, and last-updated date), stored alongside the product’s source code. There’s no separate content management system to log in to.

The main benefit is that a change to the product and the change to its help article can be reviewed and approved together. My rule is that when a change affects what customers see, the matching article is updated in the same change. Whoever reviews the work sees what the code now does and what the article now says, side by side, and can tell whether they agree.

Two habits keep this safe:

• Everything in the help folder is public. Internal notes and plans for unreleased features live elsewhere, so nothing private can be published by accident.
• An article’s filename is its web address, and those addresses are permanent. People bookmark them and search engines index them, so the website’s build fails if one disappears without a redirect.

Screenshots are generated, not taken

Screenshots are where help content goes out of date fastest, so I don’t take them by hand. Each article that has images comes with a short script that opens the real product in a browser, gets it to the right screen, and captures exactly the part of the page the article is talking about.

A few things make this work:

• It’s the real product. The screenshots come from the same application my customers use, running on a temporary database on a developer’s computer. Only the parts a screenshot can’t depend on are replaced: sign-in, and outside services like email and payments. Permissions and business rules work exactly as they do in production, so the screens are what you would see.
• The data is fictional, by design. Every screenshot shows Maple Grove Learning Center, an invented tutoring center with two locations, made-up students and families, and phone numbers and email addresses reserved for fiction. It’s defined in code and loaded through the same business logic the product uses, so details like banked make-up sessions, students on hold, and closed days come out exactly as they would for a real center. No customer data is ever involved.
• Dates move with the calendar. Scheduling rules depend on what’s in the past and what’s in the future (you can only cancel an upcoming session, for example), so the fictional center’s schedule is always anchored to the current week. This is also why my articles never refer to a specific date shown in a screenshot.
• Each script checks its work before capturing. If an image is meant to show a student marked as moved to another day, the script first confirms that the screen really says so. If the product changes and the screen no longer matches, the script fails instead of quietly saving a misleading picture.
• Quality rules are built in. Images are cropped tightly, compressed to keep pages fast, and only replaced when something visible has actually changed, so refreshing every screenshot doesn’t produce a pile of identical-looking new files.

Refreshing an article’s screenshots takes a few seconds, so there’s no longer a reason to leave an old one in place.

Publishing follows the release

The last gap is timing. The automation that copies help content to the website only runs once the product change it describes is live.

• When an article changes along with the product, publishing waits until that release has successfully reached production. The Knowledge Base never gets ahead of the product.
• When only the content changes, such as a typo fix, a clearer explanation, or a brand-new article about an existing feature, it publishes straight away, because the live product already matches.
• When the website already matches, nothing happens. No empty updates, and no out-of-date ones waiting around to be approved by mistake.

Publishing never goes straight to the live site. The automation checks the content for common mistakes (broken links, missing details, badly formed addresses) and then proposes the update as a review with a full preview of the changed pages. A person looks at the preview and approves it, and only then does the website update. If an article is removed on the product side, its page is removed from the site the same way, so old pages don’t linger.

Why I built it this way

There were simpler options. A content management system would have been quicker to set up, and screenshots taken by hand cost nothing until they need replacing. But both leave the same gaps in place, and the cost shows up later as articles drift further and further from the truth.

Building it this way gives me:

• Help content that keeps up with releases. Updating an article is part of making the change, not a follow-up task, and publishing happens on its own.
• Screenshots that are cheap to refresh, so they actually get refreshed.
• Mistakes that are caught before they’re published. A screenshot that no longer matches the product fails its check, and every update is previewed by a person before it goes live.
• No customer data on public pages, ever, because every image comes from a center that doesn’t exist.
• Content that can move at its own pace. A clearer explanation can go out the same day without waiting for a product release, while content that describes something new waits until that thing ships.