<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0"><channel><title><![CDATA[BlogWorkflow Notes]]></title><description><![CDATA[BlogWorkflow Notes]]></description><link>https://blogworkflow.hashnode.dev</link><generator>RSS for Node</generator><lastBuildDate>Wed, 18 Nov 2026 13:59:25 GMT</lastBuildDate><atom:link href="https://blogworkflow.hashnode.dev/rss.xml" rel="self" type="application/rss+xml"/><language><![CDATA[en]]></language><ttl>60</ttl><item><title><![CDATA[How to Write a Content Brief for a Technical Blog Post (One-Page Template)]]></title><description><![CDATA[Disclosure: written by the team behind BlogWorkflow, the SEO article writer mentioned near the end. This post was drafted with AI assistance and edited by…]]></description><link>https://blogworkflow.hashnode.dev/how-to-write-a-content-brief-for-a-technical-blog-post</link><guid isPermaLink="true">https://blogworkflow.hashnode.dev/how-to-write-a-content-brief-for-a-technical-blog-post</guid><category><![CDATA[SEO]]></category><category><![CDATA[writing]]></category><category><![CDATA[Blogging]]></category><category><![CDATA[technical writing]]></category><dc:creator><![CDATA[Greg]]></dc:creator><pubDate>Fri, 13 Nov 2026 10:56:04 GMT</pubDate><content:encoded><![CDATA[<p><em>Disclosure: written by the team behind BlogWorkflow, the SEO article writer mentioned near the end. This post was drafted with AI assistance and edited by a person.</em></p>
<p>Most technical posts don't fail because the code is wrong. They fail because the writer started typing before deciding who the post is for, what that reader searched, and what they should be able to do when they finish. The result is a tutorial that wanders: half setup guide, half opinion piece, with the useful part buried under a long introduction.</p>
<p>A content brief fixes that before the first paragraph. It is a one-page plan you can write in ten or fifteen minutes. It isn't a marketing document; think of it as the README for your post. Below is a template for a technical article, a filled-in example, and the checks to run before you publish.</p>
<h2>Why a brief matters more for technical posts</h2>
<p>Technical readers arrive with a specific problem, often a pasted error message or a "how do I X in Y" query. They scan for the version they're on, the command that works, and signs that the author actually ran it.</p>
<p>Google's guidance on <a href="https://developers.google.com/search/docs/fundamentals/creating-helpful-content">creating helpful, reliable, people-first content</a> asks similar questions of any page: does it provide original information or analysis, and will a reader leave feeling they've learned enough to reach their goal? A brief makes you answer those questions up front instead of hoping the draft does.</p>
<h2>The one-page template</h2>
<p>Copy this into your notes before you start writing:</p>
<pre><code class="language-text">Working title:
Reader:                 role, stack, experience level
The search:             the exact query or error they would type
Search intent:          learn a concept / fix an error / compare options / follow a setup
Versions tested:        language, framework, OS you actually ran it on
Promise:                after reading, the reader can ...
Must include:           the working example, the gotcha, the expected output
Leave out:              topics that belong in a different post
Sources to cite:        official docs, changelogs, specs
Outline:                H2s in order
Done when:              how you'll check the post before publishing
</code></pre>
<p>Each field earns its place:</p>
<ul>
<li><strong>The search</strong> keeps you honest about wording. If people search for an error message, put that message in the post, word for word.</li>
<li><strong>Search intent</strong> decides the format. A fix-an-error post should lead with the fix; a concept post can afford more background.</li>
<li><strong>Versions tested</strong> is the field most tutorials skip and the first thing readers look for. State what you ran, not what should work.</li>
<li><strong>Leave out</strong> prevents scope creep. A post about configuring a linter doesn't need a history of linters.</li>
<li><strong>Done when</strong> turns review into a checklist instead of a feeling.</li>
</ul>
<h2>An illustrative example</h2>
<p>Here is the brief filled in for a made-up post. It's an example, not a real project:</p>
<pre><code class="language-text">Working title:    Fixing "Cannot find module" after switching a Node.js project to ESM
Reader:           backend developer moving an older Node project to ES modules
The search:       "cannot find module" error after adding "type": "module"
Search intent:    fix an error
Versions tested:  the Node.js version you ran, npm, macOS and Linux
Promise:          the reader fixes the import error and understands why it happened
Must include:     the exact error text, before/after import lines, the file-extension rule
Leave out:        bundler configuration, TypeScript path aliases (separate post)
Sources to cite:  the Node.js ES modules documentation
Outline:          the error → why it happens → the fix → other causes → checklist
Done when:        every command runs on a clean checkout; the error text matches what Node prints today
</code></pre>
<p>With that brief, the outline almost writes itself, and it's obvious when a paragraph wanders: if it doesn't serve the promise, it goes.</p>
<h2>From brief to outline</h2>
<p>Turn the outline field into headings before you write any prose. A pattern that works for fix-an-error posts:</p>
<ol>
<li>The symptom, with the exact error text</li>
<li>The cause, in one paragraph</li>
<li>The fix, with copy-pasteable code</li>
<li>Other causes that produce the same error</li>
<li>A short checklist</li>
</ol>
<p>For concept posts, change the order: a plain definition, a minimal example, when to use it, when not to, and further reading.</p>
<h2>Checks before you hit publish</h2>
<p>Run these against the brief, not against your memory of it:</p>
<ul>
<li>The title and first paragraph use the reader's words from "The search".</li>
<li>Every code block was run on the versions you listed.</li>
<li>In a fix-an-error post, the fix appears before the halfway point.</li>
<li>Each claim about a tool's behaviour links to its official docs.</li>
<li>Headings describe what's in the section ("Why the import fails") rather than being clever.</li>
<li>Everything under "Leave out" stayed out.</li>
</ul>
<h2>Where tools fit</h2>
<p>You don't need software for any of this; a text file works. If you write often, though, the brief, the outline and the pre-publish checks are the repetitive parts worth standardising. That's the problem we built <a href="https://blogworkflow.ai/">BlogWorkflow</a> around: it takes one topic through search intent, research, brief, outline, draft and a QA checklist, so each step can be reviewed instead of fixed at the end. You still decide what goes in, and you still test the code.</p>
<p>If you'd like a longer <a href="https://blogworkflow.ai/resources/ai-content-workflow/content-brief-to-article-workflow-a-practical-system">content brief example</a> that follows the brief through to the draft and QA, we wrote one up on our site.</p>
<h2>Takeaway</h2>
<p>Spend fifteen minutes on a brief before your next technical post: name the reader, copy their exact search, state what you tested, and decide what's out of scope. The writing gets faster, and the post answers the question the reader actually had.</p>
]]></content:encoded></item></channel></rss>