The outline is where the article is decided
Most weak articles are not badly written. They are badly structured, and no amount of sentence-level editing repairs that — the paragraphs are fine individually and the piece still goes nowhere.
An outline is cheap to change and an article is not. Reordering four headings takes a minute; discovering after twelve hundred words that section three should have come first means rewriting everything that referred to it. That asymmetry is the entire argument for outlining, and it is why the [msm_tool slug="blog-outline"] exists as a separate step rather than a setting inside a writing tool.
Start from the question, not the topic
A topic is a noun and produces a survey. A question is answerable and produces an argument.
Container security gives you a piece that defines terms, lists considerations and recommends being careful. Which container security checks are worth running in CI and which belong in the registry gives you a piece with a position, a structure that follows from it, and a reader who knows within one line whether this is for them.
Write the question first, then answer it in one sentence. That sentence is your thesis, and every heading in the outline should be a step in getting the reader to accept it. Headings that do not serve it are the ones to cut — and they are usually the ones you were most attached to.
What a heading has to do
- Make a claim, not a label. Benefits is a label. Why scanning at build time catches less than you think tells the reader what they will get.
- Stand alone. Most readers scan headings before reading a word. The headings alone should convey the argument.
- Cover one idea. A heading whose section splits into two unrelated halves is two headings.
- Follow from the one before. If two sections could swap places without loss, the sequence is not doing any work.
Depth, and when a subheading is a lie
Three top-level sections is usually too few for anything substantial and eight is usually too many — past that the piece is trying to be two articles. Four to six is where most good posts land.
Subheadings should only appear where a section genuinely divides. A section with exactly one subheading is a structural error: nothing was divided, and a reader scanning the outline is told a distinction exists that does not.
Nesting deeper than two levels almost never survives contact with a reader. If you need a third level, the second-level section probably deserves to be its own post — which is often the more valuable discovery.
Editing a generated outline
Generated outlines have predictable faults, and knowing them makes the edit quick.
- Delete the introduction and conclusion headings. Every generated outline includes them, no reader searches for them, and naming them as sections encourages you to write filler for both.
- Merge the near-duplicates. Models produce Benefits and Why it matters as separate sections. They are one section.
- Cut the generic middle. There is nearly always a section like Best practices that contains whatever did not fit elsewhere. It is where articles go to become interchangeable.
- Reorder for dependency. Put what the reader must understand first, first. Models order by conventional importance, not by what depends on what.
- Add the section only you can write. The mistake you made, the number from your own project, the case where the usual advice fails. That section is why the article exists.
Outline as a contract with yourself
Once the outline is settled, it does two useful things. It lets you write sections out of order — starting with the one you understand best, which is usually not the first — and it makes scope creep visible, because anything you are tempted to add has to be justified against a heading that already exists.
It also survives into the published piece as your heading structure, which is what makes an article scannable and what search engines read to work out what the page covers. An outline that is a genuine argument produces headings that are genuinely informative, and that is not a separate optimisation task. It is the same work.
Revise the outline when the writing pushes back. Drafting frequently reveals that a section is empty or that two should merge. Change the outline rather than writing around it, because writing around a broken structure is exactly the effort outlining was meant to save.
What you type goes from your browser to the provider you chose, under their terms, and never through this site.