A code sample can run perfectly in your editor and fail when a reader copies it from the published page. A pasted quotation mark might change, a setup step might be missing, or the example might refer to a file the reader doesn't have. Test what will actually appear on the page, not just the draft in your notes.
Check the draft before opening the publisher
1. Confirm the post answers one clear question
Write the reader's likely goal in one sentence: “set up a Java project in an IDE” or “identify why a Linux service cannot be reached,” for example. Does the title point to that goal? Do the opening, headings, and final practical detail help the reader reach it? Save substantial side topics for separate posts rather than asking a beginner to follow several unrelated threads.
Check where the instructions expect readers to start. If they need an installed compiler, a particular shell, or permission to change a system setting, say so before the steps. Define unfamiliar terms when they first matter. Readers should be able to tell whether the instructions apply to their setup without reaching the end.
2. Verify technical claims and examples
Run the commands and code in a suitable test environment, ideally a fresh project or disposable virtual machine. Record the operating system, language version, and relevant tool versions when they affect the result. Compare filenames, paths, output, and screenshots with the written steps. If output varies by machine, label the example as illustrative.
Keep security demonstrations on systems you own or in an authorized learning lab. Remove real hostnames, access tokens, private keys, account details, and sensitive log entries from examples and screenshots. A command isn't ready to publish just because it ran: explain what it does and what permissions it needs. If a step can change configuration or data, show readers how to inspect the current state first.
Support factual claims with a reliable source or a reproducible test. Recheck tool interfaces near publication rather than trusting an old draft, and separate what you observed in your test from what readers can generally expect.
Prepare a page people can follow
3. Edit for sequence and scanability
Read the draft as someone carrying out the task. Put prerequisites before commands, actions before expected results, and troubleshooting beside the step where the problem might arise. Use headings that name the action: “Check the service status” tells readers more than “Next steps.” Break a long paragraph if it hides an instruction or limitation.
Number steps when their order matters; use bullets for independent items. Make warnings concrete by saying what could happen, when, and how to avoid it. Cut repeated explanations, but leave enough context to explain why a step is needed. Read the post once without looking at the title: does a phrase such as “this setting” still have a clear referent?
4. Review the title, description, and links
Choose a title that names the task and its scope without promising more than the post delivers. Write a short description of the result readers can expect. Set a readable URL slug before publication; changing it later may call for a redirect. Preview the title and description in the publishing interface, but don't sacrifice accuracy to fit in more keywords.
Check where every link goes and what its label says. An internal link should help with a related task, not interrupt an explanation. If you use external references, tie them to specific claims rather than letting them stand in for the procedure. Open links in the preview to catch missing pages, accidental draft URLs, and labels that no longer match their destinations.
5. Check images and accessible text
Use an image when it clarifies a step, shows an expected state, or gives readers a useful visual pause. Crop screenshots to the relevant area and obscure personal or sensitive information. Make sure screenshot text remains legible on a narrow screen, and put essential commands and instructions in the article text so readers can copy or enlarge them.
Write alt text that conveys what's relevant in the image without repeating a nearby caption. If a screenshot shows an error, name that error in the prose too. Check the heading hierarchy and make sure link labels make sense out of context. Don't rely on color alone to explain a difference—for example, by saying only that “the green result is correct.”
Run a pre-publication pass in the CMS
Pasting a draft into a content management system can change it. Before scheduling or publishing, inspect the rendered preview rather than relying on the editor view:
- Formatting: Check that code blocks retain their spacing, special characters, and line breaks, and that tables and lists remain readable on mobile.
- Media: Make sure each image loads, has appropriate alt text, and sits beside the section it supports.
- Metadata: Check the title, slug, description, category, and any required author or update information.
- Navigation: Test links and the table of contents, if the page has one.
- Visibility: Check the publication time and time zone, and confirm whether the post is public, scheduled, or still a draft.
Preview at desktop and phone widths. Watch for clipped commands, wide tables, misplaced images, and headings stranded above unrelated content. If a step depends on a screenshot, compare the previewed image with the instructions one last time.
Check the live page after publication
Open the published URL in a fresh browser session. A preview can look fine while the public page has a broken image, a caching issue, or access restrictions. Check the title and opening text, then test the most important link and any copyable command. If your site uses categories or feeds, confirm that the post appears in the right place.
Keep a record of the publication date and any version-sensitive details worth revisiting. If a post describes a Java tool's menu labels, for instance, note the version you checked. Correct substantive errors promptly. When a correction changes what readers should do, add a brief, dated note rather than leaving the earlier advice unexplained.
Save a clean test project alongside the next draft. At the final check, rerun the code sample from that project and compare its output with the published page.
