Hey everyone, been lurking for a bit and finally decided to post. I'm trying to set up a more solid content review process for our team's technical docs and blog posts. We're using a simple Git flow for content right now, but the review stage feels hit or miss. People just glance at the Google Doc and say "LGTM" without really catching the common errors.
I'm used to building CI/CD pipelines where you have linters and tests that fail a build for concrete issues. I want to create a review checklist for content that works like a good pipeline—something that actually catches things before they go live. Right now, I'm thinking of a checklist that lives in our repo's PR template. But I don't want it to be so generic it's useless.
What should be on it? I'm looking for specific, actionable items, not just "check for typos." For example, from a DevOps angle, I was thinking:
- Are all code blocks tagged with the correct language for syntax highlighting?
- Do any inline commands or paths contain placeholder values that need to be replaced?
- Are there any absolute URLs that should be relative to the site root?
But I know there's more to content than just my tech checks. How do you structure your checklist so reviewers actually use it and it catches the sneaky stuff? Do you separate "technical" from "editorial" checks? Any examples of checklists that have worked well for you would be awesome.
Learning by breaking
Hey user162, that's a great question - we actually tackled this exact problem on my team. I'm a platform engineer at a mid-sized SaaS company, and we manage all our technical docs and internal knowledge in Markdown files stored in GitHub, with automated publishing via a CI/CD pipeline to a static site. We built a review checklist into our process that catches real issues, not just typos.
Here's the checklist we enforce in our PR template, broken down by the type of error it catches:
1. **Code and Command Accuracy**
- Every code block must have a language tag defined, and we run a linter in CI that flags untagged blocks and fails the build. For inline commands, we require they be tested in a fresh container; we found about 15% of commands had missing flags or environment assumptions.
2. **Link and Reference Integrity**
- All URLs are checked for broken links (via a `link-checker` step in CI, which adds about 20 seconds to the build). Internal links must be relative, and any placeholder values like `{{HOSTNAME}}` cause the build to fail. This catches roughly 3-5 broken links per docs sprint.
3. **Sensitive Data and Placeholders**
- We scan for secret patterns (keys, tokens, internal IPs) using `gitleaks` in pre-commit hooks. It also flags generic placeholders like `[INSERT_EXAMPLE]` - we require those to be replaced with actual examples or marked as intentional with a specific comment.
4. **Reviewer-Specific Checks**
- The checklist includes a dropdown for the reviewer to confirm they've done a specific action: "I ran the commands in a clean environment" or "I checked that the steps match our current production environment." This shifts the review from passive reading to active validation, cutting post-publish corrections by about half.
My pick is embedding the checklist directly into your PR template and backing each major item with an automated check in your CI pipeline. It turns the checklist from a suggestion into a gate. For your case, start with the first two items - code block tagging and link checking - because they're easy to automate and give quick wins. If you can share whether you're using a static site generator and if your team has CI already, I can suggest specific tools.