Blog

One draft says “Wi-Fi,” another says “WiFi,” and a third says “wifi.” A style sheet settles the spelling so editors do not have to debate it with every post. Unlike a general writing guide, it records the choices a particular publication makes repeatedly: terminology, formatting, capitalization, and how to present technical instructions.

Start with the decisions editors actually need. A page they can search and use beats a long list of rules that have never come up.

Set the boundaries before collecting rules

Write down who the publication serves and what the sheet covers. A beginner-focused development and defensive-security blog might publish Java tutorials, Linux setup guides, and authorized lab exercises. Its style sheet should make those articles consistent without treating code, interface labels, and prose as interchangeable.

Be clear about what the sheet cannot override. Programming languages determine code syntax; product interfaces determine the labels readers see on screen. Accessibility and security requirements may also take priority over a spelling preference. If a rule conflicts with a verified fact, a current interface label, or a safety requirement, change the rule—not the fact.

Give the document an owner, a date, and a shared home. A Markdown file in the editorial repository works if contributors already use it. A shared document works too, provided its permissions and change history are clear. Avoid personal copies, where retired rules can linger unnoticed.

Gather decisions from published work

Review a manageable sample of recent articles: a tutorial, a comparison, and a security-related guide, if you publish all three. Look for variations that recur or could make instructions harder to follow. Check titles and headings, operating-system names, commands, paths, UI labels, version numbers, and warnings. Search the archive for likely variants instead of relying on memory.

For each candidate rule, note the variants, the preferred form, and why the choice matters. “Use Wi-Fi in prose” gives an editor something to do; “Be consistent with technology names” does not. Nor is the most common spelling in older posts necessarily right. When accuracy depends on a product name or label, check current documentation or the interface itself.

Sort the findings before turning them into rules. Sentence-case headings are a house preference. Reproducing a command exactly is an accuracy requirement. That distinction keeps a prose convention out of a code block.

Build a short, searchable structure

An editor should be able to find a rule while reviewing a sentence. Use descriptive headings and put the decision first. A first version needs only a few sections:

• Scope and priorities: audience, covered content, and which requirements take precedence.
• House language: spelling variety, punctuation, capitalization, numbers, and abbreviations.
• Technical notation: code, commands, file paths, UI labels, version numbers, and links.
• Safety and clarity: authorized exercises, assumptions, cautions, and unverified claims.
• Term list: preferred spellings and variants editors might search for.

If article templates or publishing procedures become lengthy, give them a separate home. The style sheet should usually answer “Which form do we use?” rather than “Who approves this post?”

Choose defaults, then state exceptions

Choose a spelling variety for editorial prose, such as US English. Preserve wording when quoting a source, and do not quietly change product names or UI text to fit the house default. Set a heading style, preferred forms for common abbreviations, and a rule for numerals. For example: “Spell out one through nine in ordinary prose; use numerals for measurements, versions, numbered steps, and values readers must enter.” Those exceptions keep “8 GB” and “Java 17” intact.

Say where each rule applies. “Use sentence case for editorial headings; retain the exact capitalization of commands, filenames, and product names” is safer than “Use sentence case everywhere.” If the exceptions take several paragraphs to explain, split the entry or narrow the rule.

Specify how technical material appears

Technical tutorials expose weak style rules fast. A beginner needs to tell a command from its output, a filename from a directory, and text to type from a label to click. Define how you present each, then try the rules on a real tutorial.

Code, commands, and placeholders

Use inline code for short commands, filenames, paths, environment variables, and identifiers when the publishing system supports it. Use code blocks for material readers may copy or need to inspect line by line. Decide whether command blocks include shell prompts; leaving prompts out of copyable commands reduces accidental copying. Label output separately, and identify the operating system or shell when it affects the result.

Choose a placeholder convention and explain it beside the example. “Replace example-user with your local username” is clearer than an unexplained value in a command. Do not substitute a vague placeholder for characters the syntax requires. The sheet governs how code is presented; it must not make examples invalid for their stated language or environment.

Interfaces, versions, and names

Decide how to mark UI labels, perhaps with bold text: “Select Settings.” Match the label in the version you are documenting, even when its capitalization breaks house style. For a sequence, use one consistent form, such as “Open Settings, then select Privacy.” If a menu path differs across platforms, name the platform rather than inventing a universal path.

Include a version when steps or behavior depend on it. Otherwise, an exact release number can date an explanation needlessly. Keep version identifiers as numerals, and distinguish software releases from dates and language standards. In a C++ guide, “C++20” names a standard, not the twentieth release of an application.

Make safety and evidence part of house style

In defensive-security writing, a small wording change can broaden the apparent scope of an exercise. Require procedures for network inspection or vulnerability testing to name the authorized environment. “In your own lab VM” is clearer than “on any machine” and does not suggest permission to test someone else’s system. A style rule cannot replace technical review, but it can prompt an editor to check the scope.

Set rules for warnings, including when they are needed. Before a command that deletes files, changes firewall rules, or exposes a service, tell readers what it will do and what they should check first. A warning on every command soon becomes noise. A specific one is useful: “This removes the test directory and its contents; confirm the path before running the command.”

Technical claims need boundaries too. Distinguish what you tested from what documentation states or what you inferred. “In our Ubuntu lab VM, the service started after a reboot” does not claim it always will. Name the version, configuration, or platform when a claim depends on it.

Write entries that resolve actual edits

Each entry should give a decision, its scope, and an example or exception if needed. Keep it short enough to scan:

Put rejected variants in the term list so editors can find a rule by searching for the form they want to fix. Alphabetize terms, but group broader rules by task. Document real exceptions instead of bending a rule silently in published posts. If rules conflict, state the priority: exact syntax and visible UI labels come before house typography.

Test the sheet and maintain it

Have another editor apply the draft to an unpublished article without talking them through it. Watch for hesitation, hard-to-find entries, and rules that produce the wrong result. Test a code-heavy tutorial as well as a prose-heavy guide. Fix ambiguous entries and use the revised sheet on new work. An archive-wide cleanup can wait unless an existing inconsistency misleads readers.

Keep a simple change record: date, editor, and reason for each substantive revision. Contributors can propose rules using examples from drafts, while one owner decides what becomes house style. Periodically remove duplicates and flag entries tied to obsolete interfaces or tools. Add a term when an edit recurs, not merely because an unfamiliar word appears once.

For a first maintenance check, search three recent drafts for “command line.” If the drafts vary between “command-line” as an adjective and “command line” as a noun, add the distinction with an example of each. If all three already get it right, leave the rule out until someone needs it.