DEV Community: EvvyTools

Why Code Comments and Inline Documentation Confuse Standard Readability Formulas

EvvyTools — Tue, 07 Jul 2026 09:17:41 +0000

Run a README or a docstring-heavy file through a general-purpose readability checker and you will sometimes get a score that makes no sense relative to how the document actually reads. The culprit is usually the code itself getting swept into the word and sentence count, and formulas built for prose have no concept of what a code block is.

What actually goes wrong

Readability formulas split text into words and sentences using punctuation as the primary signal, periods for sentence boundaries, whitespace for word boundaries. Code does not respect either convention. A single line like const userConfig = await fetchUserConfiguration(userId, { includeDeleted: false }); gets parsed as one enormous "word" by character count, or as multiple short sentence fragments if the formula treats semicolons and periods inside the code as sentence breaks. Either way, the resulting number reflects an artifact of the parsing, not the actual difficulty of the surrounding prose.

Fenced code blocks in markdown are especially prone to this if a readability script naively strips markdown syntax but does not specifically detect and exclude the content inside triple-backtick blocks. The comment text explaining the code might be perfectly clear, grade 8, easy to follow, while the raw code sitting next to it drags a whole-document average toward something meaningless.

Inline code spans cause a subtler version of the same problem

Even outside full code blocks, inline code spans, variableName, functionCall(), --flag-name, get counted as regular words by formulas that are not specifically stripping markdown code syntax first. A sentence like "Set the maxRetries option to control how many times fetchData() will retry before it throws a NetworkTimeoutError" contains three inline code spans that will inflate a naive word-length or syllable count, even though a developer reading that sentence experiences it as perfectly normal technical prose.

How to get a number that actually means something

Before running a readability check on technical content, strip fenced code blocks and inline code spans first, and run the formula only against the remaining prose. Most markdown parsing libraries make this straightforward, since code blocks and inline code spans are already distinctly tagged in the parsed document tree. A reading level analyzer or similar tool applied to raw markdown without this preprocessing step will produce numbers that are not comparable across documents with different amounts of embedded code, which makes tracking a readability trend over time actively misleading.

Comments extracted from source code deserve the same treatment, but from the opposite direction: pull just the comment text out of the source file and run the formula against that, ignoring the code it is attached to. This gives you an honest signal about whether your inline documentation itself is clear, separate from whatever the code surrounding it looks like.

Why this matters beyond getting a clean number

Teams that try to enforce a readability standard on technical writing without handling code exclusion end up with a check that fires unpredictably, sometimes flagging genuinely clear prose because of an unrelated code block sitting nearby. That kind of noise is exactly what causes a team to stop trusting an automated check and eventually disable it, even though the underlying idea, keeping documentation prose readable, was sound. Fixing the code-stripping step first is what makes the rest of a readability-based quality process actually usable for technical content.

A worked example showing the size of the distortion

Take a short README section: three sentences of plain explanatory prose, followed by a five-line code block, followed by two more sentences of prose. Run the whole section through a formula with no code stripping and you might see a reported grade level of 16 or higher, driven entirely by the code block's long variable names and lack of natural sentence boundaries. Strip the code block first and run the same formula against just the five sentences of prose, and the honest number might be grade 8 or 9, a completely different picture of how accessible the actual writing is.

This gap is not a minor rounding difference. It is large enough to make a document look like it needs a rewrite when the writing itself is already fine, or worse, to hide a genuinely dense paragraph of prose behind a code block that happens to offset the average in the other direction. Neither outcome helps a team trying to actually improve their documentation, which is why code stripping has to happen before the formula runs, not as an afterthought applied to the output.

Building this into your own tooling

If you are writing a script to check documentation readability across a repository, budget time for the preprocessing step before you budget time for picking a formula. A regex-based approach that strips triple-backtick fenced blocks and single-backtick inline spans will handle the majority of cases in standard markdown. YAML frontmatter blocks, HTML comments, and embedded configuration snippets deserve the same treatment, since none of them represent the actual prose you are trying to evaluate.

Test your stripping logic against a few real files from your own documentation before trusting the readability numbers it produces. Documentation with heavy use of inline code for configuration keys, environment variable names, or CLI flags will show the distortion most clearly, and confirming your preprocessing handles those cases correctly is worth the extra half hour before you start acting on the scores it generates.

Tables, admonition blocks, and other markdown extensions

Fenced code and inline code spans are the most obvious culprits, but they are not the only markdown constructs that confuse a naive readability check. Tables get rendered as rows of pipe-separated cells in raw markdown, and a formula run against the raw table syntax will count table borders and alignment markers as word-like tokens, producing nonsense. Admonition blocks, the colored "note" or "warning" boxes many documentation frameworks support, often use custom syntax extensions beyond standard markdown, which a generic stripping script will not recognize unless you specifically account for the framework you are using.

The safest approach is to render the markdown to a structured format first, an abstract syntax tree or a parsed HTML document, and then walk that structure extracting only the nodes that represent actual prose paragraphs and list items. This is more setup work than a quick regex, but it scales much better across a documentation site that uses tables, admonitions, and custom components alongside plain paragraphs, since each node type can be explicitly included or excluded rather than guessed at with pattern matching that will eventually miss an edge case.

What this looks like in an actual CI check

Once the stripping and parsing step is solid, wiring it into continuous integration is straightforward: run the readability formula only against the extracted prose nodes for each changed file, compare against a baseline, and flag genuine outliers. The value of doing the preprocessing correctly compounds here, because a CI check that occasionally fires on a false positive from an unstripped code block will train contributors to ignore it within a few weeks, the same failure mode any noisy automated check eventually suffers from regardless of how good the underlying idea was.

For a broader look at why different readability formulas can disagree with each other even on ordinary prose, see EvvyTools' explainer on why readability scores disagree on the same paragraph.

References: the CommonMark specification documents exactly how fenced code blocks and inline code spans are defined in markdown, the Google Developer Documentation Style Guide covers writing clear inline comments and prose separately from code samples, and the Write the Docs community maintains further resources on documentation tooling and quality checks for technical writing teams.

How to Add a Readability Check to a Documentation CI Pipeline Without Blocking Every Pull Request

EvvyTools — Tue, 07 Jul 2026 09:13:25 +0000

Docs teams that adopt readability tooling usually make the same early mistake: wiring the check up as a hard CI gate on day one. A new contributor pushes a perfectly reasonable API doc, the pipeline fails on a grade-level threshold nobody explained to them, and the whole team quietly starts ignoring the check within a month. Here is a sequence that avoids that.

Step 1: Run the check in report-only mode first

Before any pull request can fail because of it, add the readability check as a CI step that posts a comment with the score but does not block merging. This gives you real data on your existing docs corpus, what your typical grade level actually is today, before you pick a threshold that might be unrealistic for your content.

Most CI systems (GitHub Actions, GitLab CI, CircleCI) support posting a PR comment from a script's output. Point that script at a reading level analyzer or an equivalent formula library, and have it comment the Flesch-Kincaid grade level and word count on every changed markdown file.

Step 2: Collect two to three weeks of baseline data

Let the report-only check run across real pull requests for a few weeks. Look at the range of scores your existing, already-published docs are landing in. If your published API reference sits at grade 12 to 14 because of unavoidable technical vocabulary, a rule that requires grade 9 or below is going to fail on legitimate content constantly.

This step also surfaces which formula fits your content best. If Gunning Fog consistently reports two to three grades higher than Flesch-Kincaid on your docs because of technical terms tripping its complex-word counter, that is useful to know before you commit to enforcing either one.

Step 3: Set a threshold based on your own baseline, not a generic target

Once you have real numbers, set the CI threshold at something like "one grade level above your current median," not an arbitrary number pulled from a generic style guide that was never written with your docs in mind. This keeps the check meaningful: it catches genuine outliers, sentences or pages that got noticeably harder to read, without punishing normal technical writing.

Step 4: Make the failure message actionable

A failing check that just prints "readability score too high" teaches a contributor nothing. Have the script identify the specific sentences driving the score up, typically the longest ones or the ones with the most polysyllabic words, and print those in the CI output. Contributors who can see exactly which sentence to shorten will fix it in one commit instead of guessing.

Step 5: Exempt reference material explicitly, not implicitly

Decide upfront which doc types are exempt from the grade-level ceiling (API references, changelogs with version-specific terminology) versus which types should be held to it strictly (onboarding guides, tutorials, README introductions). Encode that as a path-based rule in the CI config rather than leaving it to reviewer judgment, which drifts over time and creates inconsistent enforcement.

Following this sequence, report-only first, baseline before threshold, actionable failures, explicit exemptions, gets you a check that catches real regressions instead of one that gets muted in the team's notification settings within a month.

For background on why different formulas can disagree by several grade levels on identical text, see the longer explainer on why readability scores disagree on the same paragraph.

Handling the edge cases that break naive implementations

A few situations trip up readability CI checks that work fine in testing. Code blocks and inline code spans inside markdown will confuse a formula that is not stripping them first, since a long variable name or a multi-line code sample will get counted as extremely long "words" and "sentences," wrecking the score for a page that is otherwise perfectly readable prose. Make sure your script strips fenced code blocks and inline code spans before running any formula against the remaining text.

Tables and bullet lists have a similar problem: formulas built around sentence structure do not know what to do with a table cell or a one-word bullet point, and will sometimes report wildly inflated or deflated scores on pages that are mostly structured data rather than prose. Consider running the check only against prose paragraphs, and skipping table cells, code blocks, and single-line list items entirely.

Auto-generated content, API reference pages built from OpenAPI specs or docstrings, should usually be excluded from the check altogether rather than exempted case by case. That content is typically generated from a template your team does not hand-edit line by line, so a readability score on it is not actionable in the way a score on hand-written prose is.

What good looks like after a few months

Teams that get this right end up with a CI check that fires rarely, catches real problems when it does, and gets fixed in a single commit each time. The failure comments reference specific sentences, the threshold reflects the team's actual writing rather than a generic target, and reference material with an unavoidably higher technical vocabulary floor is excluded rather than fought against. That is a very different experience than the blanket, ungraduated check most teams start with, and it is the difference between a tool the team trusts and one they quietly disable six months later.

Rolling this out to a team that has never had a readability gate before

If your team has zero existing tooling around prose quality, readability is a reasonable first check to introduce, precisely because it can start as report-only and never actually block anyone while you build trust in it. Announce it as an informational addition before it ships, not a new requirement. Nothing kills adoption of a quality gate faster than a team discovering a new blocking check in their pull request queue with no warning and no context for why the number matters.

Pair the rollout with a short internal doc, even three or four sentences, explaining which formula you picked, why, and what the current baseline looks like. This matters more than the tooling itself. A contributor who understands "we use Flesch-Kincaid, our docs currently average grade 10, and pages above grade 13 usually mean an unnecessarily long sentence, not necessarily bad writing" will engage with a failing check productively. A contributor who just sees a red X with an unfamiliar formula name attached will not.

Measuring whether the check is actually helping

After a quarter or two of running the check as a hard gate, look back at what it actually caught. Good outcomes look like: a handful of genuinely improved sentences, contributors who mention the check positively or reference it when writing new docs, and a stable or slowly improving baseline score over time. Bad outcomes look like: contributors routinely disabling or overriding the check, a growing list of path-based exemptions because the threshold keeps hitting content it should not, or the check firing so rarely that nobody remembers it exists. If you are seeing the bad outcomes, it is worth revisiting the threshold and the exemption list rather than assuming the check itself was a mistake, since most of these failure modes trace back to a threshold that was set before the baseline data step above was actually done.

Tooling references: GitHub Actions documentation covers how to post PR comments from a workflow script, the textstat project on PyPI ecosystem hosts several open-source readability formula libraries you can wire into a pipeline directly, and the Vale linter project is a popular open-source tool for enforcing broader prose style rules in CI alongside readability scoring.

Why Your HTTP Security Headers Affect More Than Your Security Score

EvvyTools — Mon, 06 Jul 2026 09:14:29 +0000

Most teams treat security headers as a compliance checkbox: run a scanner, get a letter grade, add whatever headers get you from a C to an A, move on. That framing misses something worth knowing, which is that several of these headers also shape how crawlers and browsers evaluate your site in ways that show up outside any security audit.

Content-Security-Policy can silently break rendering

A Content-Security-Policy header that's too restrictive can block inline scripts or styles your page actually needs, which is a problem you'll usually notice fast in a browser but can be much harder to catch when it's a crawler rendering the page instead of a human. Google renders pages the way a browser would before judging their content quality, so a CSP that blocks a script your layout depends on can produce the same "page looks broken" outcome for a crawler that a misconfigured robots.txt rule can, just through a completely different mechanism.

Referrer-Policy affects your own analytics

Referrer-Policy controls how much of the referring URL gets passed along when someone clicks a link from your site to another one, or from another site to yours. Set it too aggressively (no-referrer everywhere) and you lose visibility into which of your own pages are driving outbound clicks in your analytics. Set it too permissively and you might be leaking full query-string URLs, including anything sensitive that ended up in a URL parameter, to third-party sites your users click through to. strict-origin-when-cross-origin is a reasonable default for most sites: full referrer on same-origin navigation, origin-only across origins.

X-Frame-Options and embeddability

If you ever want your own content embeddable in an iframe elsewhere (a widget, a partner integration, a preview card), a blanket X-Frame-Options: DENY will block that entirely, with no partial-allow option. Content-Security-Policy's frame-ancestors directive is the more flexible modern replacement, letting you allowlist specific origins instead of an all-or-nothing rule. Worth checking which one your stack is actually sending, since a lot of default configs still ship the older, less flexible header.

HSTS has a real, sticky downside if you get it wrong

Strict-Transport-Security tells browsers to only ever connect to your domain over HTTPS, for a duration you specify, and browsers cache that instruction aggressively. If you set a long max-age and then later need to run a subdomain over plain HTTP for some reason, users who already cached the HSTS policy simply can't reach it until the policy expires, no matter what your server does. Set it deliberately, understand the includeSubDomains and preload flags before turning them on, and don't copy a max-age value from a template without knowing what you're committing to.

Permissions-Policy can quietly disable embeds you rely on

Permissions-Policy (the successor to Feature-Policy) lets you turn off browser features like camera, microphone, geolocation, or autoplay for your own page and for anything embedded in it. Teams usually add it for the obvious reason: lock down features you don't use so a compromised third-party script can't quietly turn on the microphone. That part works as advertised and is worth doing.

Where it gets messy is with third-party embeds you actually want. A YouTube video embed expects autoplay and sometimes fullscreen to be allowed for the frame it sits in. A payment widget or an identity verification vendor often needs camera or publickey-credentials-get passed through explicitly, because permissions don't propagate to iframes by default under a restrictive policy. If you write a blanket Permissions-Policy that disables everything and never add the specific allow= exceptions those embeds need, the embed doesn't error loudly, it just silently fails to do the one thing it was there for, like a video that never autoplays or a scanner that never gets camera access. Debugging that is annoying precisely because the page looks fine, nothing throws a console error a casual glance would catch, and the feature just doesn't work.

The fix is boring but effective: whenever you add a third-party embed, check its documentation for which permissions it expects the parent frame to delegate, and add those explicitly rather than copying a maximally locked-down policy from a template and assuming it'll be fine.

Cross-Origin-Resource-Policy and Cross-Origin-Opener-Policy can break resource loading

Cross-Origin-Resource-Policy (CORP) and Cross-Origin-Opener-Policy (COOP) exist mainly to isolate your page from cross-origin attacks like Spectre-style side channels, and browsers have been pushing sites toward setting them more aggressively over the last few years. The side effect that catches people off guard is that both headers can block perfectly legitimate cross-origin loads if the values don't match what the other side expects.

Set Cross-Origin-Resource-Policy: same-origin on an asset your own CDN serves from a different subdomain than your main site, and the browser will refuse to let your main page load it, because from the browser's point of view that's a different origin making the request. The asset returns fine over the network, dev tools show a 200, and the resource still never renders because the policy blocked it after the fact. The usual fix is cross-origin or same-site instead of same-origin, depending on how your subdomains are actually laid out.

COOP causes a subtler version of the same problem with popups and OAuth flows. A strict Cross-Origin-Opener-Policy: same-origin can sever the window.opener reference a login popup relies on to communicate back to the page that opened it, which breaks the "log in via popup, then refresh the parent page" pattern some auth providers use. If you support any third-party login flow that depends on window messaging between a popup and its opener, test that flow specifically after tightening COOP, because it's not the kind of break that shows up in a normal page load.

CORS headers and CDN caching don't always agree

Access-Control-Allow-Origin and CDN caching interact in a way that trips people up because each system is reasoning about the request independently. If your CDN caches a response and that cached response included an Access-Control-Allow-Origin header scoped to one specific origin, every subsequent request for that same cached asset gets served with the same CORS header, regardless of which origin is actually asking for it this time.

That means a font or JSON file that legitimately needs to be fetchable from multiple origins can end up cached with only the first requesting origin's value baked into the response, silently breaking cross-origin fetches from every other origin until the cache expires or gets purged. The standard fix is to add Vary: Origin alongside your CORS header so the CDN treats different origins as different cache entries instead of collapsing them into one. It costs you some cache efficiency in exchange for correctness, which is usually the right trade for anything served to more than one origin.

Where this connects back to crawling

Headers and crawl directives are two separate mechanisms that occasionally interact in confusing ways, similar to how robots.txt and a page's noindex meta tag are separate mechanisms people conflate. I wrote a longer breakdown of the robots.txt side of that confusion here, including why blocking a folder in robots.txt doesn't remove already-indexed pages the way people expect.

I run new deployments through EvvyTools' HTTP Security Header Grader alongside a normal Lighthouse pass, mostly because it catches the headers that don't show up in a standard performance audit at all.

For deeper reference, MDN's HTTP headers documentation covers every header mentioned here in more depth, OWASP's Secure Headers Project has a solid checklist if you're setting these up from scratch, and the W3C's CSP specification is the authoritative source if you need to resolve an edge case the summaries don't cover.

How to Test a Wildcard Pattern Before You Ship It, Not After

EvvyTools — Mon, 06 Jul 2026 09:14:28 +0000

Wildcard and regex patterns share a specific failure mode: they almost always match more, or less, than the person writing them assumed. The pattern reads correctly in your head. The engine reading it doesn't share your assumptions, and it will match exactly what you wrote, not what you meant.

Step 1: Write down what you actually want matched and excluded

Before touching the pattern itself, list concrete example strings, some that should match, some that shouldn't. This sounds obvious and gets skipped constantly. A pattern meant to catch query-string URLs (?sort=price) needs explicit test cases for URLs with a literal ? in a different context, like an encoded character in a slug, so you can confirm the pattern doesn't also catch those.

Write this list down somewhere durable, not just in your head while you iterate. A plain text file with one example per line, prefixed with MATCH or NO-MATCH, takes two minutes to create and becomes the seed for the automated test suite described further down. Skipping this step is how a pattern ships that technically works on the three examples the author tried and fails on the fourth one a user actually sends.

Step 2: Test the narrowest version first

Start with the most specific pattern that covers your primary case, then broaden it deliberately, testing after each change. Going the other direction, starting broad and trying to add exceptions, tends to produce patterns nobody can fully reason about six months later, because each exception was bolted on to fix one specific test case without re-checking the others.

The narrow-first approach also makes code review easier. A reviewer can look at a tight pattern and confirm it matches the stated intent in a few seconds. A pattern that's been broadened repeatedly with negative lookaheads bolted on for each edge case usually takes longer to verify than to rewrite from scratch, and reviewers often just wave it through instead, which is how subtle bugs survive review.

Step 3: Check greedy vs. lazy quantifiers explicitly

.* and .*? (greedy vs. lazy) produce dramatically different results on strings with repeated delimiters, and this is one of the most common sources of "why did this match the whole string instead of just the part between the first two quotes" bugs. Test any pattern with a quantifier against a string containing the delimiter more than once, not just the simple single-occurrence case that usually gets written first.

A concrete example: matching text inside quotes with ".*" against "first" and "second" greedily matches from the first quote to the last, swallowing both pairs and the word "and" in between. Switching to ".*?" stops at the first closing quote instead. Neither choice is universally correct, it depends on what you're parsing, but you have to test both against a multi-occurrence string to know which one you actually need.

Step 4: Run it against real production data, not synthetic examples

Synthetic test strings are written by the same person who wrote the pattern, which means they tend to avoid the exact edge cases that would actually break it. Pulling a sample of real URLs, log lines, or user input and running the pattern against all of them surfaces mismatches a clean synthetic test suite won't.

If you don't have production data handy, the next best option is user-submitted content that's already messy by nature: free-text form fields, uploaded filenames, or copy-pasted URLs with tracking parameters attached. These sources reliably contain the stray whitespace, mixed casing, and unexpected punctuation that a hand-written test list tends to omit.

Step 5: Confirm the match groups, not just whether it matched

A pattern can technically "match" while capturing the wrong groups, which is often worse than not matching at all, since downstream code will happily extract the wrong substring and keep going. Always inspect the actual captured groups during testing, not just the pass/fail result.

This matters most with nested or optional groups, where a group can be present in the match but empty, or absent entirely and return null depending on the engine. Code that assumes a captured group is always a non-empty string will throw or silently produce garbage the first time that assumption breaks, so test the group values explicitly, not just whether the overall pattern returned true.

Step 6: Test for catastrophic backtracking before the pattern touches user input

If any part of a pattern accepts user-supplied text and runs it through a regex with nested quantifiers, like (a+)+ or (.*)*, you need to test what happens on adversarial input before shipping, not after a server hangs in production. This failure mode is called catastrophic backtracking, or ReDoS (regular expression denial of service): certain input strings cause the engine to try an exponential number of ways to fail a match, and a string of just a few dozen characters can pin a CPU core for seconds or minutes.

The test for this is straightforward: take your pattern and feed it a string designed to almost match but not quite, repeated enough times to be interesting, for example thirty repetitions of a character followed by one character that breaks the match. Time how long the pattern takes to run against it. If the time grows sharply as you add a few more repetitions rather than staying roughly flat, the pattern has backtracking risk and needs to be rewritten, usually by making quantifiers more specific or using atomic groups or possessive quantifiers if your engine supports them. This test costs a few minutes and catches a class of bug that's genuinely dangerous if the pattern ever runs against anything a user controls, like a search box, a filter, or a custom validation rule.

Step 7: Check the pattern against the actual engine flavor it will run in

Not every regex engine agrees on syntax. PCRE, POSIX, and JavaScript's engine all diverge on details like lookbehind support, possessive quantifiers, and how character classes handle Unicode, and a pattern that works when you test it in one context can behave differently, or fail to compile at all, in another. This matters most when the same pattern is duplicated across a frontend written in JavaScript and a backend written in Python or another language, which is common for form validation that's checked client-side and re-checked server-side.

If your pattern needs to work identically in both places, test it in both places, not just the one you happened to write it in first. A quick way to catch this early is running the exact same pattern and test strings through each target language's regex implementation and diffing the results. A mismatch means the pattern needs a compatible rewrite, or the two checks need to tolerate slightly different behavior on purpose. Python's official re module documentation is a solid reference for exactly which syntax it supports and where it differs from PCRE, since some patterns that look identical on paper parse differently between the two.

Step 8: Turn your test cases into an automated suite that runs in CI

Manual testing catches problems the day you write the pattern. It does nothing for the day six months later when someone tweaks the pattern to fix an unrelated bug and breaks a case nobody remembered to check by hand. The fix is turning the match and non-match examples from Step 1 into an actual automated test, however small, that runs whenever the pattern changes.

This doesn't need to be elaborate. A simple test file with an array of { input, shouldMatch } pairs and a loop that asserts each one, wired into whatever test runner your project already uses, is enough. The goal isn't full coverage of every conceivable string, it's a tripwire: if a future edit to the pattern breaks a case that used to pass, the test fails in CI before it ships, instead of surfacing as a support ticket after a user hits it in production. Patterns that guard anything security-relevant, like input sanitization or auth token formats, benefit from this most, since a silent regression there is the kind of bug that doesn't announce itself.

Why this discipline matters beyond regex specifically

This same testing discipline applies almost identically to robots.txt wildcard rules, which use a simpler pattern syntax but fail in the same way: a Disallow: /*? rule looks like it targets query strings specifically, and does, but also matches any path containing a literal ? anywhere, which can catch URLs nobody intended to block. I broke down that exact failure mode and several others in a longer piece here, if you're dealing with crawl directives specifically rather than application code.

I use EvvyTools' Regex Tester for quick iteration since it shows capture groups and match boundaries live as you edit, which speeds up step 5 considerably compared to running a script and printing results manually.

For deeper reference, MDN's regular expressions guide is the best general-purpose explainer, and the regexp info reference site documents cross-engine differences (PCRE vs. JavaScript vs. POSIX) that matter if your pattern needs to work identically across a frontend and a backend written in different languages.

How to Write a Content Brief a Writer Will Actually Follow

EvvyTools — Sun, 05 Jul 2026 09:15:33 +0000

A brief that's too loose gets ignored in practice because the writer has to make every structural decision from scratch anyway, which means the brief added planning overhead without actually reducing the writer's workload. A brief that's too rigid also gets effectively ignored, or worse, followed to the letter, because following it word for word tends to produce flat, mechanical prose that reads like it was assembled from a checklist rather than written by a person with a point of view. The useful middle ground here is narrower than most content briefs actually land on, and hitting it takes a specific, repeatable set of steps rather than just "writing a more detailed brief."

Step 1: Separate the non-negotiables from the suggestions

Start by explicitly splitting your brief into two distinct lists, labeled differently in the document itself. The first list is what must be true in the final draft no matter what: the target keyword, the required internal links, the word count range, the intended audience. The second list is everything else that's useful context but not a hard requirement: tone notes, a rough optional outline, a couple of competitor examples worth glancing at. Writers who can't easily tell which parts of a brief are requirements and which are merely suggestions tend to default to treating everything in the document as a requirement, which is exactly what produces flat, template-shaped drafts that all sound the same regardless of who wrote them.

Step 2: Give the angle, not the outline

State the specific angle the piece needs to take in one or two sentences, rather than handing over a full five-level H2/H3 outline for the writer to fill in like a form. "This piece should explain why the tool's default setting causes confusion for new users specifically, using a concrete before-and-after example from a real support ticket" tells the writer what the piece is actually for and why it needs to exist. A detailed pre-built outline, by contrast, tells the writer to fill in blanks under headings someone else already chose. The first approach produces original structure suited to the specific angle. The second reliably produces a shape that every reader who has seen enough content in this space will recognize as templated on sight.

Step 3: Name the one thing that has to be true by the end

Every brief should include a single clear sentence answering "what does the reader now know or believe by the end of this piece that they didn't before they started reading it." If you genuinely cannot write that sentence, the brief doesn't have a clear enough job yet, and the draft that comes out of it won't either, no matter how skilled the writer is. Writers who don't know the actual goal of a specific piece default to covering the topic generically and safely, which is exactly where a lot of interchangeable, forgettable content in any given niche comes from in the first place.

Step 4: Include real examples, not placeholder text

A brief with "[insert example here]" as a placeholder gives the writer nothing concrete to work from and just defers the hard thinking to draft time. A brief that includes an actual example, even a rough, imperfect one, anchors the tone and the level of specificity you actually want far more effectively than an adjective like "conversational" or "authoritative" ever will on its own. Show the writer what good looks like instead of describing it abstractly and hoping they infer the same thing you have in your head.

Step 5: Leave the sentence-level decisions alone entirely

Do not specify exact sentence length, paragraph rhythm, or precise phrasing anywhere in the brief itself. This is the step most briefs get wrong, usually with genuinely good intentions behind the mistake: an editor wants visual and tonal consistency across a whole site, so the brief slowly starts dictating rhythm sentence by sentence over successive revisions. The result across a body of work is prose that all sounds statistically similar regardless of which writer actually produced it, and somewhat ironically, prose that reads as more mechanically uniform than natural, unconstrained human writing usually does on its own. Save structural consistency notes for a separate style guide document the writer references independently, and keep the brief itself focused on what the piece needs to accomplish.

Why this matters for more than just writer experience

A brief that over-specifies structure at the sentence level produces finished text with unusually low sentence-length variance and unusually consistent phrasing across different writers on the same team, which happens to be almost exactly the statistical signature that makes writing look machine-generated even when every single word was typed by a human being. This isn't purely an aesthetic problem confined to how the prose feels to read. Teams that have started running finished content through AI detectors as an informal quality check have found that heavily templated briefs produce a measurably higher false-positive rate on genuinely human-written drafts, simply because the brief had already flattened the natural variance out of the writing before a human writer ever touched the page.

The Content Marketing Institute has published general guidance on brief structure that's worth cross-referencing against whatever template your own team is currently using. The Nielsen Norman Group's usability research covers how overly rigid content templates measurably affect reader engagement and comprehension, which is really the flip side of the same underlying problem: briefs that over-constrain writers at the sentence level tend to under-serve the actual readers of the finished piece too, not just the writer producing it.

A worked example of the two-tier split in practice

Consider a brief for a piece about choosing a database index strategy. The non-negotiables list might read: target keyword "composite index order," minimum 1400 words, one internal link to the site's own indexing tool, audience is backend developers with some SQL experience but no deep DBA background. The suggestions list might read: consider opening with a slow-query war story, a rough optional structure moving from single-column to composite to covering indexes, maybe reference a specific ORM's default behavior if it fits naturally. Notice how the second list uses words like "consider" and "maybe" throughout, deliberately signaling to the writer that these are options to weigh, not steps to execute in order. A writer handed this brief still has to make real decisions: which war story, whether the ORM reference actually earns its place, how long each section needs to be to serve the angle rather than to fill a template slot.

What happens when teams skip the two-tier split

Without an explicit split, briefs tend to accumulate detail unevenly over time as different editors add notes to a shared template. A well-meaning editor adds "should probably mention indexing overhead on writes" as a suggestion, a stricter editor later reads that same line as a requirement and starts rejecting drafts that omit it, and within a few months the "suggestions" section has quietly become a second non-negotiables list that nobody explicitly decided to create. The fix isn't more discipline from any single editor, it's making the two categories structurally distinct in the document itself, different heading, different formatting, so the ambiguity can't creep back in through normal editorial drift.

If you're building content briefs at any real volume across a team, the free content brief builder by EvvyTools generates the two-tier structure described above, non-negotiables clearly separated from suggestions, from just a target keyword and a rough topic description, and deliberately leaves every sentence-level decision to the individual writer by design rather than pre-specifying them. The Society for Technical Communication publishes broader guidance on structuring writer instructions that's worth a look if you're designing a brief template from scratch rather than adapting an existing one. For more on why detector-based content quality checks sometimes end up catching templated writing style rather than actual AI usage, there's a related, more detailed piece on why AI detectors flag human writing as AI-generated that's worth reading before your own team adopts a detector as a hard quality gate on contributed or commissioned writing.

Why Technical Writers Get Falsely Flagged by AI Detectors More Than Anyone Else

EvvyTools — Sun, 05 Jul 2026 09:15:32 +0000

If you write documentation, API references, or runbooks for a living, and you've ever run a draft through an AI detector out of curiosity or because a client asked you to, you may have noticed something uncomfortable: your score tends to run higher than you'd expect. Not because you used AI to write any of it, but because of how disciplined technical writing is structured at a sentence level, which happens to overlap statistically with the patterns detectors are built to catch.

The style guide is working against you

Most technical writing style guides mandate the exact features an AI detector treats as suspicious signals. Active voice, consistent terminology used the same way every time it appears, short declarative sentences, and parallel structure across similar sections of a document. A style guide that says "use the same term for the same concept every single time" is directly asking you to lower your own vocabulary diversity score, because vocabulary diversity is literally a measure of how much you vary your word choices across a passage. A guide that says "keep sentences short and direct, avoid subordinate clauses where possible" is asking you to lower your sentence-length variance, which is exactly what detectors read as low burstiness, one of their core suspicious signals.

None of this is a coincidence in the sense that both language models and disciplined technical writers are optimizing toward the same statistical target: predictable, low-noise prose that's easy to parse quickly under time pressure. The model gets there because it was trained explicitly to minimize surprise at each next word. The technical writer gets there because a confused reader in the middle of a production incident at 3am is a reader who cannot afford ambiguity in a runbook step. Two completely different reasons for writing, arriving at the same statistical destination, and a detector cannot tell the difference between the two just by looking at the finished text.

Where this actually causes real, costly problems

Some organizations now run detector checks on contributed documentation, whether from external contractors or from community contributors to open source docs, as a spam filter or a plagiarism check before accepting a contribution. A contractor who has been writing clean, consistent API reference documentation for a decade can trip a detector's threshold simply by doing their job well and following the house style guide, and then has to explain a statistical artifact to a project maintainer who has never heard the word "perplexity" used this way and doesn't know what a false positive rate even means in this context.

This is a real, measurable cost, not a hypothetical inconvenience. A flagged contribution that gets held up for extra review, or a contractor invoice that gets questioned because of a detector score attached to the deliverable, wastes time on a signal that was never validated for this use case in the first place. The fix isn't to deliberately write worse, more chaotic documentation just to dodge a score, that would be actively harmful to the people relying on the docs. The fix is for whoever is reviewing flagged content to understand what the score is actually measuring, and what it demonstrably is not measuring, before treating it as evidence of anything at all.

What actually distinguishes AI text from disciplined human text

If detector scores alone aren't reliable for this specific population of writers, what does actually help separate the two in practice? A few things a purely statistical model has no access to at all: whether the writing references specific internal system names, unusual edge cases, or incident history that the writer would only plausibly know from direct, hands-on experience with the system being documented; whether the phrasing matches the same author's prior documentation in tone, structure, and characteristic word choices over time; and whether there are small, characteristic imperfections, a slightly awkward but functionally correct explanation of a genuinely tricky edge case, that tend to show up specifically in writing from someone who actually debugged the thing they're describing rather than someone summarizing it secondhand.

None of these checks are automatable the way a single detector score is, which is exactly why they get skipped in practice in favor of the faster, cheaper, and considerably less reliable signal. The Google Developer Documentation Style Guide and the Microsoft Writing Style Guide both codify, in explicit detail, the consistency-first approach that produces this exact statistical overlap with machine-generated text, for anyone who wants to see the actual published guidance technical writers across the industry are following and understand why the overlap exists structurally rather than coincidentally.

A concrete example of the mismatch in practice

Take a real sentence from a hypothetical API changelog: "The rate limit was increased from 100 to 500 requests per minute for authenticated endpoints." That's a textbook agentless passive, following house style exactly as written, because the changelog reader cares about the rate limit change, not about which engineer on the platform team flipped the config value. Run that same sentence through a detector tuned on general web prose and it will likely register as unusually predictable: common vocabulary, a passive construction, no rhetorical flourish anywhere in it. Now compare it to a sentence from that same writer's personal blog written the same week: "I spent way too long last night trying to figure out why our rate limiter kept doubling requests, and it turned out to be a stale cache entry nobody had touched in months." Same person, wildly different statistical profile, because the genre and the audience are different. A detector comparing only the changelog sentence against a generic human-writing baseline has no way to know it's looking at disciplined technical prose rather than machine output, and that's the exact gap that produces a false positive on a writer who did nothing wrong.

A reasonable process fix for teams that rely on these scores

If your team relies on an AI detector as part of a contribution review process for documentation, it's worth running a few samples of your own team's most experienced, most trusted writers' historical documentation through the same detector first, before using any threshold from that tool against outside contributors. Seeing your own baseline false-positive rate on writing you already know for a fact is human and original is the fastest way to calibrate how much weight the score deserves in your actual review process, and it often produces a genuinely uncomfortable but useful result. The Write the Docs community guidelines are a good general reference for documentation review practices that don't lean on a single automated signal as a gate.

There's a fuller breakdown of the underlying statistical reasoning, including the specific research on which populations of writers get flagged most often and why, over on EvvyTools' recent piece on why detectors misfire on genuine human writing. If you want to check where your own writing currently sits before anyone else runs it through a detector and hands you a number with no context, the site's own AI content detection tool breaks the score down sentence by sentence instead of handing you one opaque figure to argue about after the fact.

Why Your Team's SQL Style Guide Keeps Getting Ignored

EvvyTools — Sat, 04 Jul 2026 09:15:32 +0000

Most teams that write one don't actually have a SQL style guide problem. They have an enforcement problem wearing a style guide's clothes. The guide exists, it's reasonable, someone even linked it in the onboarding doc, and six months later half the queries in the codebase don't follow it anyway, and nobody quite remembers when it stopped mattering.

Photo by Luis Quintero on Pexels

The guide is a suggestion, and suggestions decay

A style guide that lives in a wiki page or a README has no mechanism forcing anyone to check it before writing code. New team members don't read onboarding docs closely enough to internalize keyword-case preferences from page four of a style guide, especially in their first week when there are a dozen more urgent things competing for attention. Existing team members forget it exists the moment they're deep in a debugging session and just want the query to work. Neither group is being careless. The guide simply has no teeth, and documentation without enforcement decays at a predictable rate regardless of how well it was written.

Manual review catches maybe half of it

Reviewers are supposed to be the backstop, but reviewers are humans looking at logic, not whitespace police. A reviewer who's focused on whether a join is correct will let inconsistent casing slide because flagging it feels like nitpicking, and nobody wants to be the person who blocks a PR over select versus SELECT when the actual logic is sound. So it slides, repeatedly, until the guide is more theoretical than real, and the gap between "documented standard" and "actual codebase" widens every sprint.

There's also a social cost reviewers are implicitly weighing that rarely gets said out loud: flagging style issues repeatedly on the same person's PRs reads as nitpicking even when it's technically correct, and most reviewers would rather preserve the working relationship than win every formatting argument.

The fix isn't a stricter guide, it's removing the human step

The teams that actually maintain consistent SQL formatting long-term almost always have one thing in common: a formatter running automatically, either in a pre-commit hook or a CI check, so the convention gets applied without anyone deciding to apply it. The style guide becomes documentation of what the automated tool already enforces, rather than the primary enforcement mechanism itself, which is a meaningfully different (and much more durable) role for it to play.

This matters because it removes the social cost of enforcement entirely. Nobody has to be the person nagging a teammate about casing in a PR comment. The tool just does it, silently, every time, and the conversation about style only comes up once, when the team decides what the automated config should say, instead of recurring on every single pull request forever.

A pattern worth recognizing in other parts of your stack

This isn't a SQL-specific problem, it's a general pattern about any written standard that lacks automated enforcement. API design guidelines, commit message conventions, and naming standards for cloud resources all suffer from the exact same decay curve: documented once with good intentions, followed closely for a few weeks, then quietly abandoned as soon as the initial enthusiasm fades and nobody's actively checking. If your team has other written standards that feel similarly unenforced, the same diagnosis probably applies, and the same fix (automate the check, stop relying on memory) is probably the right move there too.

Recognizing this pattern is useful because it reframes the SQL formatting problem as not really about SQL at all. It's about the general principle that a standard without an automated check is really just a suggestion, no matter how carefully it was written or how good the reasoning behind it is.

What this looks like in practice

Format on save in the editor, a pre-commit hook that blocks a commit if formatting doesn't match, or a CI step that fails the build. Any of the three works, and most teams end up with some combination of at least two for redundancy. What doesn't work is a written guide with no automated check behind it, because the guide is only as strong as someone's memory in the moment they're writing code, and memory under deadline pressure is not a reliable enforcement mechanism.

Getting from "guide nobody follows" to "convention that sticks"

If your team is at the "we have a guide nobody follows" stage, the fastest unstick is picking a formatter, running it against a few real queries to confirm the output matches what your team actually wants, and then wiring it into whichever step (save, commit, or CI) your team is most likely to actually respect given how your workflow already operates.

https://evvytools.com/tools/dev-tech/sql-formatter/ is a fast way to preview what a given convention produces before you commit your team to it, with no setup required to just see the output on a real query. The reasoning behind why different formatters default to different conventions in the first place is covered in more depth in this piece on SQL formatter keyword case and indent style.

For how other language communities solved the same enforcement problem, Go's gofmt documentation and the Prettier project are both worth studying, since they turned "the style guide" into "the tool" for their respective ecosystems and largely ended the recurring debate that SQL teams are still having today. The Black documentation is another good reference point for how Python's community made the same transition from written convention to automated enforcement.

Why SQL lagged behind other languages on this

It's worth asking why application languages solved this years before most SQL codebases did. Part of the answer is tooling maturity: Go shipped gofmt as part of the language's own toolchain from very early on, which meant there was never really a period where teams had to choose to adopt formatting discipline, it was just there by default from day one. SQL has no single toolchain in that sense. It's a query language embedded across dozens of different application stacks, ORMs, migration tools, and BI platforms, each with its own conventions and none of them treating a shared formatter as a first-class default the way go build does.

That fragmentation is exactly why the problem persists longer in SQL-heavy codebases than in, say, a pure Go or Python repo. There's no single obvious tool everyone already has installed. Picking one, configuring it, and wiring it into your specific stack is a deliberate decision a team has to make, rather than something that comes for free with the language. That extra friction is real, but it's also a one-time cost, and it's considerably smaller than the ongoing cost of a style guide nobody follows.

The signal that tells you it's time to fix this

If your team has had the same "can we agree on SQL formatting" conversation more than once, that's the signal. A style question that keeps resurfacing despite being nominally settled isn't actually settled, it's just quiet for a while between flare-ups. That pattern is the clearest sign that documentation alone isn't going to solve it, and that the fix has to be structural rather than another round of writing the guide down more clearly.

How to Add an Automated SQL Formatting Check to Your CI Pipeline

EvvyTools — Sat, 04 Jul 2026 09:15:30 +0000

If your team has agreed on a SQL style but nobody's enforcing it, you'll drift back to inconsistent formatting within a month. New hires don't know the unwritten convention, tired developers on a Friday skip the extra step, and the style guide quietly stops mattering because nothing actually checks it. The fix is to enforce it in CI instead of trusting everyone to remember every time.

Photo by Wolfgang Weiser on Pexels

Step 1: Pick a formatter and lock its config

Whatever formatter your team uses, pin its version and its configuration (keyword case, indent width, comma style) in a config file committed to the repo. If the formatter's defaults can drift between versions, an unpinned dependency will silently reformat your entire codebase on the next npm install or pip install, which is its own kind of chaos and defeats the whole point of having a consistent standard in the first place.

Treat this config file the same way you'd treat an ESLint or Prettier config: check it in, review changes to it deliberately, and don't let it get bumped as a side effect of an unrelated dependency update.

Step 2: Add a check script, not a fix script

The CI check should fail the build if formatting doesn't match, not silently reformat and commit on your behalf. A script that runs the formatter against every changed .sql file, diffs the output against the committed version, and exits non-zero on any difference is enough:

for f in $(git diff --name-only origin/main -- '*.sql'); do
  sql-formatter "$f" > /tmp/formatted.sql
  diff -q "$f" /tmp/formatted.sql || exit 1
done

This keeps formatting as a deliberate developer action (run the formatter locally, commit the result) rather than something CI does silently on your behalf, which avoids surprising force-pushes or unexpected diffs showing up on merge that nobody remembers authorizing.

Step 3: Scope it to changed files only, not the whole repo

Running the check against every SQL file in the repo on every PR will fail on day one if your codebase has years of inconsistently formatted queries sitting in it already. Scope the check to files touched in the current diff so you're only enforcing the new convention going forward, and clean up the historical backlog separately, in its own dedicated PR, on its own schedule, reviewed on its own merits as a pure formatting change.

Step 4: Document the exception path

Some generated SQL (migrations produced by an ORM, vendor-provided scripts, third-party seed data) shouldn't be reformatted, either because it's not really "yours" to restyle or because reformatting it would make future diffs against the upstream source harder to read. Exclude those paths explicitly in the CI config rather than letting developers add ad-hoc # noformat comments that nobody remembers the exact syntax for six months later.

Step 5: Make the fix path obvious in the failure message

A CI failure that just says "formatting check failed" sends people hunting for what to do next, usually into a Slack thread asking someone else how to fix it. Have the script print the exact command to run locally to reformat and pass the check, so the failure resolves in one copy-paste instead of a back-and-forth conversation that costs more time than the original formatting issue would have.

Step 6: Decide what happens on a formatting-only PR

Once the check exists, you'll eventually get a pull request that's purely a reformat with no logic changes, either from the initial rollout or from someone cleaning up a file they happened to be touching anyway. Treat these as their own category: fast to review (diff the AST or the query's semantic content if your tooling supports it, not just the text), but still worth a real look, since a bug in the formatter itself could theoretically alter behavior in an edge case. Don't let "it's just formatting" become an excuse to merge without any review at all.

Step 7: Revisit the config occasionally, but rarely

A locked formatting config is a feature, not a limitation, but it shouldn't be permanently frozen either. If the team's needs change (a new database engine gets adopted, a new hire strongly prefers a different comma style and makes a good case for it) revisit the config deliberately, as its own decision, rather than letting it drift through unrelated PRs. The goal is stability with an explicit, rare escape hatch, not an unchangeable rule enforced for its own sake.

Why this is worth the setup cost

The one-time cost of wiring this up is small compared to the recurring cost of relitigating the same case-and-comma argument every few months, which is what happens by default once a style guide has no enforcement behind it. Once this check exists, new team members follow the convention automatically because the CI system teaches them on their very first PR, rather than a wiki page they may or may not have read closely.

Once this is running, the case-versus-lowercase, leading-comma-versus-trailing debates mostly disappear, because the CI check makes the team's choice binding instead of aspirational. For background on why formatters disagree on these defaults in the first place, see this breakdown of SQL formatter keyword case and indent conventions. If you want to spot-check formatting output manually before wiring up CI, EvvyTools has a browser-based SQL formatter that's a fast way to see the target output for a given query before you commit your team to a specific config.

For general CI pipeline patterns beyond SQL specifically, GitHub's Actions documentation and GitLab's CI/CD documentation both cover the check-and-fail pattern used here in more general terms, and either is a good reference if you're setting up your very first automated formatting gate. If your stack also includes a general-purpose linter, the ESLint documentation is a useful comparison point for how a mature ecosystem structures the same "check, don't auto-fix in CI" pattern for application code.

Handling the rollout without blocking every open PR at once

If you're adding this check to a repository that already has open pull requests in flight, don't flip the CI gate to blocking on day one. Every open PR touching a .sql file will suddenly fail, not because of anything the author did wrong on that PR specifically, but because the check is now retroactively applying to code written before the standard existed. Run the check in warn-only mode for a week or two first, let people see and fix the failures at their own pace, then switch it to a hard block once the backlog of in-flight PRs has mostly cleared out naturally.

This staged rollout matters more than it might seem. A hard, blocking gate that lands with zero warning reads as hostile to whoever's PR happens to be open at the time, even though the goal (consistent formatting) is genuinely good for the whole team. A short warning period costs almost nothing and avoids that entirely preventable friction.

Measuring whether the gate is actually working

After a month or two of the check running, it's worth actually looking at whether it's doing its job. A useful signal: are formatting-only PRs still showing up regularly, or has the codebase stabilized into consistent formatting with the check mostly just confirming what developers are already producing locally before they push? If formatting-only fixup commits keep appearing regularly, that's a sign either the local tooling isn't wired in well enough (developers are relying on CI to catch what a pre-commit hook should catch earlier) or the config needs another look. Either way, the CI check gives you a concrete, measurable signal instead of a vague sense that "formatting seems better now."

Why Joist Spacing Cascades Into Beam and Footing Costs on a Deck Build

EvvyTools — Fri, 03 Jul 2026 09:57:00 +0000

Joist spacing on a deck reads like a small decision. Twelve inches on center, sixteen, twenty-four - pick one, put a check mark next to it on the plan, move on. What most build guides do not explain clearly is that the check mark you put on that line rewrites every other number on the material list. The beam gets bigger or smaller, the footings deepen or shallow, the post count shifts, and the fastener count follows.

Here is why the cascade happens and why the number is worth thinking about carefully before it locks in.

Photo by Muharrem Alper on Pexels

Spacing changes the tributary load per joist

A joist carries the deck load between the two beams (or between the ledger and one beam) it spans. The area of deck load it carries is called its tributary area, and it is the joist span times half the distance to the next joist on each side.

At 12-inch on center spacing, each joist carries the load from 12 inches of deck floor. At 24-inch spacing, each joist carries 24 inches of floor - twice as much. The joist itself sees more load per foot of length, which is why the span table shortens the maximum span when the spacing widens: a 2x8 might span 12 feet at 16-inch spacing but only 10 feet at 24-inch spacing.

So changing spacing changes the joist size you need for the same deck length. Widen the spacing, and you might have to upsize from 2x8 to 2x10, which increases the cost per linear foot of joist even though the joist count went down.

Spacing changes the beam load

The beam under the joists carries the total load from every joist that lands on it. Fewer joists at wider spacing does not mean less load - the total floor area is the same. But the load per contact point on the beam is bigger, which means the beam and its posts have to handle bigger point loads.

For most residential decks this shows up as either upgrading the beam from a doubled 2x10 to a doubled 2x12, or reducing the maximum span between posts. The American Wood Council publishes the beam span tables that quantify this.

The rule of thumb: wider joist spacing means either a beefier beam or more posts. Neither is free. Sometimes both.

Spacing changes the footing depth and diameter

Footings have to handle the point load from the post above. When joist spacing widens and beam loads concentrate, footings can get bigger too. Local frost line determines minimum depth, but diameter and reinforcement come from load.

A residential deck with joists at 16-inch spacing might have 12-inch diameter footings. Push to 24-inch spacing on the same footprint and load, and depending on beam layout, footings could go to 14 or 16 inch diameter. That is one bag of concrete more per footing, and if there are eight footings, that math is real.

Spacing changes the fastener count

Fewer joists means fewer joist hangers, fewer joist-to-ledger structural screws, and fewer joist-to-beam nails. Those all get cheaper.

But fewer joists means more fasteners per joist connecting the boards, because each board has to bear on fewer support points. If the deck was going to have 26 boards at two fasteners per joist per board:

13 joists (16-inch spacing): 676 board fasteners
9 joists (24-inch spacing): 468 board fasteners

The board fastener count drops. But the hanger and structural connection savings from fewer joists partially offset the gain, and if you had to upgrade the joist size to allow the wider spacing, the joist-per-piece cost went up. Connector manufacturers like Simpson Strong-Tie publish fastener specs and load ratings that are worth checking against your specific joist size and connector before you commit to a fastener count.

Why this is easy to get wrong on a takeoff

Most manual takeoffs work one line at a time. Someone counts joists based on the spacing that day, then counts boards, then quotes a beam based on a rule of thumb, then quotes footings based on the beam.

Change spacing at any point and the person doing the takeoff has to re-derive every other line. Miss any of them and the material list disagrees with the plan by one line item that will show up as a shortage or an overrun.

The fix is to model the cascade once and let the inputs drive it. Spreadsheets work. Calculators built for the purpose work better because they include the span-table lookups and code minimums that a homegrown spreadsheet usually skips.

The free decking calculator from EvvyTools handles the cascade end to end: joists, beams, posts, footings, and fasteners recalculate together when spacing changes, plus a 20-year cost comparison between wood and composite. Running the same deck at 16-inch and again at 24-inch shows the whole downstream difference in one comparison.

The detailed writeup of how spacing decisions cascade through the plan, when to pick each spacing, and what board manufacturers require lives in the guide on choosing deck joist spacing for composite or wood boards if you want the full breakdown.

Photo by Sema Bedia Bağçalı on Pexels

What the numbers look like in practice

Take a straightforward 12x16 residential deck as a worked example. Same footprint, same live load, same boards, only spacing changes:

16-inch spacing: 13 joists, 2x8 joist size, doubled 2x10 beam, 4 posts, 4 footings, roughly 26 boards
24-inch spacing: 9 joists, 2x10 joist size, doubled 2x10 beam with a possible mid-span brace, 5 posts, 5 footings, roughly 26 boards
12-inch spacing: 17 joists, 2x8 joist size, doubled 2x10 beam, 4 posts, 4 footings, roughly 26 boards

The board count is unchanged because the deck footprint is unchanged. Everything else shifts. Which of the three is cheapest depends on your local lumber prices and whether the upsize from 2x8 to 2x10 costs more than the four joists saved.

Why estimators default to 16-inch on center

Almost every residential deck estimate you will see starts at 16-inch on center. This is not a code minimum. It is the spacing that works with the widest range of common boards, in the widest range of common patterns, at the widest range of common deck sizes. It is the safe default that fits almost everything without forcing an upsize or a downgrade anywhere in the cascade.

That is why a contractor who does not know your board choice yet will quote 16-inch. It is not laziness. It is optionality. It leaves the door open for you to change from wood to composite, or from straight-across to diagonal, without redoing the framing plan. Widening to 24-inch closes some of those doors. Tightening to 12-inch is easy to add if the load justifies it later.

Understanding this is why "why did you pick 16-inch" is often not a useful question to ask a contractor early. The more useful question is "does 16-inch still make sense given the board I picked, or should we reconsider."

The framing decision in one sentence

The joist spacing you pick is not just about how far apart the joists sit - it is about the total load path from the boards down through the joists to the beam to the posts to the footings. Every one of those layers gets sized against a load that spacing changes.

Pick spacing first, run the material list against it, and every downstream number falls out of the calculation instead of getting guessed at line by line. The International Residential Code publishes the numeric floor for all of this if you want to sanity-check what your local building department is enforcing.

For related planning writeups and other DIY estimation walkthroughs, the EvvyTools blog has a growing set of them.

Get the cascade right on paper. Frame to the paper. The deck goes up faster and the material list balances at the end.

How to Build a Deck Material Spreadsheet Before You Order Lumber

EvvyTools — Fri, 03 Jul 2026 09:55:11 +0000

The mistake most DIY deck builders make on the material order is treating the joist count, the beam layout, and the board count as three separate numbers to look up in three different places. They are not separate numbers. They are one calculation with joist spacing at the top and everything else cascading from it. A spreadsheet that models the cascade catches the errors that a paper takeoff misses.

Here is how to build one that actually holds up when the lumber yard calls to confirm the order.

Photo by www.kaboompics.com on Pexels

Set up the inputs at the top

The spreadsheet starts with the values that drive everything else. Give these their own cells so the rest of the sheet reads from them:

Deck length (feet)
Deck width (feet)
Joist spacing (inches on center) - typically 12, 16, or 24
Joist orientation (which direction the joists run)
Board type (pressure treated wood, cedar, composite)
Board width (5/4-inch wood, 1-inch composite, 2x6 solid)
Board pattern (straight or diagonal)
Live load (pounds per square foot, typically 40)

Every cell below reads from these. Change joist spacing from 16 to 12 in one place and the whole material list updates.

Calculate joist count

Joists run perpendicular to the deck boards. If the boards run the long way (typical), the joists run the short way. The count is:

joist_count = ceil(long_dimension_inches / joist_spacing_inches) + 1

For a 12x16 deck with joists running the 12-foot direction and 16-inch on-center spacing:

joist_count = ceil(192 / 16) + 1 = 12 + 1 = 13

The plus one is for the joist at the starting edge - you need a joist at both ends. Forget it and you are one joist short on install day.

Calculate joist length

Joist length is the short dimension of the deck (assuming boards run the long way), plus a small allowance for how the joists connect to the ledger and beam. Most yards sell in 2-foot increments (10, 12, 14, 16). Round up to the next available length.

joist_length_needed = short_dimension_ft + 0.5   # feet
joist_length_ordered = ceil(joist_length_needed / 2) * 2

Calculate joist size

Joist size depends on span and spacing. The American Wood Council publishes the residential span tables that all this comes from. For pressure-treated southern pine at 40 pounds per square foot live load:

2x6: span up to about 9 feet 6 inches at 16-inch on center
2x8: span up to about 12 feet 6 inches
2x10: span up to about 15 feet
2x12: span up to about 17 feet

Put the span table in a lookup range on the sheet. A VLOOKUP or INDEX/MATCH keyed off joist span and spacing picks the right size automatically. The advantage of a lookup over hard-coded values: change deck size or spacing and the joist size updates without you re-checking the table.

Calculate board count

Boards run the long direction and land on joists. For 5/4-inch or 1-inch nominal boards (about 5.5 inches actual width), including a small gap between boards:

board_count = ceil(short_dimension_inches / (board_actual_width + gap_inches))

For 12-foot-wide deck with 5.5-inch actual-width boards and a 1/8-inch gap:

board_count = ceil(144 / 5.625) = 26 boards

Add 5 to 10 percent for cuts, waste, and defect selection. Boards do not come clean of knots and splits, and you will discard a few.

Calculate beam size and footing count

Beams support the joists. Beam size depends on the tributary area of the joists that land on it, which comes from spacing and joist span. For most residential decks under 16 feet on the joist side, a doubled 2x10 or a doubled 2x12 beam works, with beam posts on 6- to 8-foot centers.

post_count_along_beam = ceil(beam_length_ft / max_post_span_ft) + 1

Footing count matches post count. On most residential decks the footing depth depends on your local frost line, which is a value your building department publishes. The USDA plant hardiness zone map is a rough proxy if you cannot get the exact frost-line depth from the town.

Calculate fasteners

Fasteners scale with joist count and board count:

Structural screws or nails for joist-to-beam and joist-to-ledger: about 4 per joist connection
Board fasteners: typically 2 fasteners per joist per board (or the equivalent hidden clip count for composite)
Hangers: one hanger per joist per connection point (typically one at the ledger)

hanger_count = joist_count
board_fastener_count = board_count * joist_count * 2

Buy 10 percent extra fasteners. They are the cheapest line item on the list and running out mid-install is a Saturday killer. If you are picking specific hangers and structural screws, Simpson Strong-Tie publishes maps from board manufacturer to compatible connector - worth checking before you order.

Photo by Mark Stebnicki on Pexels

Add a running cost column

Column A the item, column B the count, column C the unit cost, column D the extended cost. Look up unit costs from your local yard - the delivery price desk will quote per-piece rates for pressure-treated, composite, cedar, or whatever you are ordering. Adding an "as of date" cell in the corner reminds you when prices need to be refreshed.

Add the 20-year check

Composite boards cost 2 to 4 times more than pressure-treated wood upfront. They also do not need to be re-stained every few years. A row that adds staining supplies and labor for wood every 3 years for 20 years - or the equivalent replacement cost of a wood deck at year 15 versus composite lasting the full 20 - is what makes the composite-vs-wood cost conversation honest.

Skipping this row is why "wood is cheaper" is only true for the first estimate and rarely true for the life of the deck. The specifics vary by climate, so if you want a reality check on how quickly untreated southern pine actually degrades in your area, the US Forest Service publishes durability studies that hold up well over multi-decade windows.

Cross-check against a calculator

Once the spreadsheet is done, run the same inputs through the EvvyTools Decking Calculator and compare. If the joist count matches, the board count matches within 5 percent, and the beam size matches, your spreadsheet math is good. If not, one of the two has a bug worth finding before the order goes in. The full explanation of how joist spacing changes the cascade is written up in the guide on choosing deck joist spacing for composite or wood boards and the code reference is the International Residential Code at ICC.

What the spreadsheet catches that paper does not

The pattern of DIY deck material errors is almost never one big mistake. It is usually a small change that did not propagate. You went from 16-inch spacing to 12-inch because the boards changed, but you forgot to recalculate the joist count. You changed the board type from wood to composite, but you did not update the beam size or the fastener count. A spreadsheet with all the inputs at the top makes those cascades automatic.

Anyone comfortable with a spreadsheet can build one in an evening. The reward is a delivery slip and a framing plan that agree - which is the whole ballgame on a DIY deck.

More project-planning writeups with the same pattern live at the EvvyTools blog, and other calculators for related DIY estimates are indexed at the EvvyTools tools directory.

Six Free Running Calculators That Plan a Race Better Than a Spreadsheet

EvvyTools — Thu, 02 Jul 2026 13:08:03 +0000

Runners who plan races in spreadsheets end up in one of two places. Either the spreadsheet is a personal masterpiece that took a year to build, or it is a broken formula they copied from a forum in 2019 that quietly rounds the wrong way. Free specialized calculators do the same math faster and with fewer subtle errors. Here are six that cover the full training cycle from base mileage through race day, and none of them require an account or a subscription.

Photo by RUN 4 FFWPU on Pexels

1. Riegel formula race predictor

The single most cited race prediction is the Riegel formula, which projects a longer race time from a shorter one using a power function. Any calculator that runs this formula honestly is useful. The version at EvvyTools exposes the exponent so you can adjust for a less trained aerobic base, which most default calculators do not do.

If your only tool is the default Riegel exponent, the marathon projection from a fast half PR will be optimistic by 8 to 15 minutes for a first-time marathoner. The ability to nudge the exponent from 1.06 to 1.08 or 1.10 is what makes the number honest.

2. Mile split table generator

A split table is a mile-by-mile plan for a race. Generating one by hand from an average pace works, but it does not handle the conservation of the first 5K, the maintenance of miles 4-16, or the honest miles 17-20. A tool that produces the full table for a specific goal time, in your chosen units, and lets you export it to a wristband-sized print is worth more than the 30 minutes of arithmetic it saves.

The EvvyTools split output is one option. Another is the built-in split table view on the Runner's World site, which has the advantage of years of iteration but the disadvantage of requiring a slightly slower workflow to print. Either works for a first marathon.

3. Pace conversion between units

If you train in kilometers and race in a mile-based country, or vice versa, you need a fast conversion tool. Not because the math is hard, but because eyeballing 5:00 per kilometer as 8:03 per mile at 6 AM on race day is where errors happen.

The Wikipedia entry on pace has the underlying formulas. Any calculator that does both directions cleanly is fine. The one at EvvyTools supports both units in the same interface and shows the split table in whichever unit you chose, which is what actually matters at the starting line.

4. Race pace by heart rate zone

For runners training with heart rate zones (the classic Zone 2 through Zone 5 model), a calculator that translates race distance into a target zone is useful for calibrating effort in training. The reference on the underlying model is in the Wikipedia entry on VO2 max and the derivative Karvonen heart rate reserve formula. A marathon is typically raced at the top of Zone 3 or the bottom of Zone 4 for most runners, which is significantly below the pace runners naturally drift toward when they feel fresh.

Any calculator that produces target HR ranges from a max HR input is useful for verifying that your goal race pace lines up with your aerobic ceiling. If the target HR for your goal pace is above your lactate threshold, the goal pace is not physiologically sustainable and needs to come down.

5. Cumulative training load and taper predictor

Not every training decision is about race day. The intermediate decisions in weeks 4 through 8 of a training block, when mileage should peak and taper should begin, benefit from a tool that shows the aggregate load curve. Free training load calculators, of which several exist in the community, help visualize when to back off and when to push.

The exact calculator matters less than the discipline of updating it weekly. A number that gets checked once produces the same insight as no calculator at all. A number that gets updated every Sunday produces the taper timing that most self-coached runners get wrong.

6. Race day pace band generator

The last calculator in this list is the smallest and most useful. A pace band is a paper wristband with target elapsed times printed for each mile marker. On race day, you glance at your watch at each mile, compare to the band, and know instantly whether you are on plan.

Most runners produce these ad-hoc from a spreadsheet. A calculator that outputs a print-ready pace band, sized for your goal time and adjusted for course profile if the tool supports it, is a small piece of paper that makes a large tactical difference. The tools directory at EvvyTools is worth browsing for the exact outputs you need for a specific race.

Photo by Jean Marc Bonnel on Pexels

The pattern across all six

The six tools have one thing in common. Each one replaces a spreadsheet formula with a purpose-built interface that handles the common edge cases (rounding, unit conversion, elevation adjustment) without asking the runner to think about them. The runner spends the training block on running, not on debugging their calculator.

None of these tools is complicated. The distinction is that they are set up correctly out of the box. A spreadsheet you built in 2019 has whatever assumptions you made in 2019, whether or not you remember them. A tool from a maintained source has current assumptions and gets corrected when the underlying formulas evolve.

The companion guide on marathon pacing explains how to translate these calculator outputs into an actual race plan, and the general EvvyTools blog covers the training-side questions that determine whether the race plan is defensible in the first place.

Why free calculators beat paid apps for most runners

The paid running apps that dominate the market bundle calculators with training plan generation, workout logging, and social features. For runners who want all of that in one place, they are worth the money. For runners who already have a training plan and just need pace math on race week, they are overkill.

A dedicated free calculator opens in 200 milliseconds, produces the output you need, and gets out of the way. It does not require an account, does not push notifications, and does not ask for your credit card. The tradeoff is that it does not know anything about your training history. If you have that history in a separate log (a paper training journal, a spreadsheet, or an app you already use for logging), the calculator on race week just needs to do the arithmetic.

For most self-coached runners, the split is: use whatever you already use for logging your training, and use a fast standalone calculator for race week pace math. Merging both into one paid tool is a preference, not a requirement.

What to test in the last two weeks

Two weeks before your marathon, run a final calibration of every tool you plan to use on race day. Cross-check the split table output against your goal time. Confirm the pace units match what your watch will report. Print the pace band if you plan to wear one, and verify the times are legible. This is a 15-minute exercise that catches misconfigured settings before race morning, which is not the time to discover them.

The final tactical rule is worth repeating: use two independent calculators and cross-check the results. If two tools produce the same split table, you have a plan. If they disagree by more than a few seconds a mile, one of them is misconfigured and it is worth finding out which before race day, not after.

How to Build a Race Split Table for Your First Marathon

EvvyTools — Thu, 02 Jul 2026 13:08:00 +0000

A split table is a mile-by-mile plan for how fast you intend to run each mile of a race, adjusted for course profile, weather, and the tactical realities of running in a crowd. Elite runners have coaches who produce these tables for them. Everybody else usually writes their goal pace on a wristband and hopes for the best. This is a walkthrough of how to build a real split table, in about 30 minutes, for a first marathon.

Photo by Vijay Saiwal on Pexels

Step 1: Pick a goal pace your training actually supports

The starting point is not aspirational. It is your training data. Use the pace from the last four miles of your best 20-mile long run as the anchor. Subtract roughly 20 to 40 seconds per mile to estimate marathon pace. That estimate is your ceiling.

If your best 20-mile long run finished at 9:45 per mile, a defensible marathon goal is somewhere around 9:15 to 9:25 per mile. That produces a 4:02 to 4:07 marathon. Anything faster is aspirational and the split table should be built for the honest number.

Step 2: Compute average pace for the goal

Average pace equals goal time divided by 26.2 miles. Do the arithmetic yourself even if the tool does it for you, because errors in this step compound across the whole race.

For a 4:00 goal: 240 minutes divided by 26.2 miles equals roughly 9.16 minutes per mile, which is 9:09.5 per mile. Round to 9:10 for the plan, or 9:09 if you want a small buffer. The free race pace calculator from EvvyTools produces this to two decimal places and shows the exact per-mile total.

Step 3: Build the miles 1-3 conservation

Race adrenaline and crowd energy will make you feel faster than you are. Your first 3 miles should be planned at 10 to 15 seconds per mile slower than goal pace. For a 4:00 goal at 9:10 average, the first 3 miles are 9:20 to 9:25.

The split table for miles 1 through 3 looks like:

Mile 1: 9:22 (elapsed 9:22)
Mile 2: 9:22 (elapsed 18:44)
Mile 3: 9:20 (elapsed 28:04)

This is not banking time later. It is refusing to spend energy that you will need in the second half.

Step 4: Fill in miles 4-16 at goal pace

Once you have thinned out from the starting crowd, settle into goal pace. This is the aerobic middle of the race, and it should feel repeatable and steady.

Miles 4-16: 9:10 per mile
Elapsed at mile 16: roughly 2:26:14

If you feel great in this section, ignore it and hold pace. If you feel bad, ignore it and hold pace. Neither feeling is a reliable signal for the second half. The Wikipedia entry on the marathon explains the physiology of why the middle miles are misleading. The lesson is to trust the plan more than the legs in this window.

Step 5: Fill in miles 17-20, the honest miles

This is where the plan continues at goal pace, but effort will noticeably rise. You are approaching the wall in glycogen terms and your form will start compensating.

Miles 17-20: 9:10-9:15 per mile
Elapsed at mile 20: roughly 3:03:04

If you have to slow slightly to 9:15 for a mile or two to stay controlled, that is fine. The goal is to arrive at mile 20 with enough left to hold the last 10K without a collapse.

Step 6: Plan the final 10K by contingency, not by wishful thinking

The last 10K is where positive splits come from. Do not plan a fixed pace here. Plan two variants:

Variant A (if you feel controlled at mile 20): Hold 9:10 to 9:15 pace for miles 21-26.2. Small negative split possible if the last 5K feels manageable.

Variant B (if effort has climbed sharply by mile 20): Slow to 9:20-9:25 for miles 21-24, then reassess. Do not force a pace that has stopped being sustainable. Losing 30 seconds a mile is a small cost. Losing 90 seconds a mile because you tried to force 9:10 and blew up is a large one.

The runner who plans for both variants finishes near their goal. The runner who plans only for variant A and is forced into variant B at mile 22 usually finishes 15 minutes slower than they should have, because they did not switch modes fast enough.

Step 7: Apply weather adjustments

Every 5 degrees Fahrenheit above 55 costs roughly 4 to 10 seconds per mile at marathon pace. Humidity above 70 percent compounds. If race-day forecast is 65 degrees and 75 percent humidity, revise the goal pace by 10 to 20 seconds per mile before the race. Do not force the pre-planned pace into an environment it was not built for. Runner's World publishes standardized heat adjustment tables, and the Jack Daniels coaching formulas are worth reading before you finalize.

Step 8: Apply course elevation adjustments

Flat course: no adjustment. Downhill start (Boston, New York): expect the first 5 miles to feel deceptively easy and hold conservative pace anyway. Rolling hills: mentally mark the uphill miles as 10 to 20 seconds slower and downhills as 5 to 10 seconds faster. Hilly finish (Newton hills): reserve 30 to 60 seconds of buffer specifically for those miles.

Draw the elevation profile once and annotate the split table with which miles are the hardest. This is the difference between a plan built for the race in front of you and a plan built for a flat treadmill run.

Step 9: Print two copies

One goes on your race bib or wristband. One goes to your support crew if you have one. Both should include the goal times at miles 5, 10, 13.1, 20, and 26.2, so you can check yourself at each mile marker and adjust in real time if you are running consistently ahead of plan (slow down) or consistently behind plan (either accept the new pace or diagnose why).

Photo by Aedrian Salazar on Pexels

The check most first-timers skip

Before you leave for the race, verify the total of the split table equals your goal time exactly. If your table adds up to 3:58:47 for a 4:00 goal, either your average pace is slightly too fast, or you have a rounding error. Fix it before race day.

The companion guide on pacing a first marathon walks through how to translate this table into actual pacing discipline during the race, and the EvvyTools tools directory has the calculators for splits, race prediction, and unit conversion in one place. The most important thing about a split table is that you built one. The second most important thing is that you trust it more than your legs in the first hour.

The mistake most runners make with the table on race day

The single most common failure mode of a split table is not that it was built badly. It is that the runner threw it away by mile 5 because the pace felt too slow. The plan on paper says 9:22 for miles 1 through 3, and the crowd is running 8:50, and the runner decides the plan was too conservative and speeds up. This is the exact mistake the table was built to prevent.

The mental discipline is to accept that the first 5K is going to feel slow to easy, and that this feeling is the plan working correctly. If your first mile felt exhausting at goal pace, either the goal is too fast or you did not warm up properly. If the first mile felt easy, that is what the plan intended. Speeding up because it felt easy is how you turn a 4:00 finish into a 4:18 finish. The runners who trust the table finish near goal. The runners who abandon it usually miss by 10 to 20 minutes and blame the training rather than the pacing.

What to do if you fall off pace by mile 15

If by mile 15 you are consistently 15 to 30 seconds per mile behind the split table, do not try to make up the time in miles 16 to 20. That is the exact strategy that produces the wall. The right move is to accept a slightly slower finish, hold the current pace steady, and let the final 10K unfold at whatever pace stays sustainable. A 4:07 finish with a controlled last 10K feels vastly better than a 4:15 finish that included a 20-minute walk. Your body will thank you the next morning as well.

The corollary is that a split table is not sacred. It is a starting hypothesis. The mid-race version of the plan is to hold whatever pace is honest for the next 10K, using the table as a benchmark rather than an obligation. That is the mature use of the tool, and it separates first marathoners who finish strong from those who suffer.