Writing and Optimising a Complete Article
Go from keyword to published page: write a brief, answer first, make it skimmable, check its structure with real code and use a publish checklist.
In this lesson you will
- Write a one-page brief
- Open with the answer
- Make a page skimmable
- Check structure and publish
About 18 minutes
A keyword and a blank page
Elena has chosen her keyword: ‘meal prep for one’. She has a page address in her map and a date in her calendar. Now she faces the blank page. Her first draft, written fast, is one long block of text. It mentions the topic, but nobody would stay to read it. This lesson walks through writing one article well, from a short brief to the moment you press publish.
Start with a brief
A brief is half a page of notes you write before you write the article. It stops you wandering. Write down:
- The main keyword and the intent. What exactly does the searcher want?
- The reader. A beginner? A busy parent? Write for one real person.
- The promise. One sentence on what the reader will be able to do after reading.
- The outline. The H2 headings, in order.
- What only you can add. Your own photos, prices, mistakes or numbers.
- Links. Which pages will you link to, and which pages should link to this one?
Answer first, then explain
Open with the answer. If the search was ‘meal prep for one’, the first two sentences should say what it is and what the page will give. Readers who find their answer right away trust you more and stay longer. The detail comes afterwards, in sections that each answer one sub-question. Make each H2 heading a clear label, and where it fits, use the main keyword or a close variation in one of them, as you would in normal speech.
Make it easy to skim
- Short paragraphs. Three or four lines is plenty on a phone.
- Lists for items and steps, tables for comparisons.
- Descriptive subheadings so a reader can jump to the part they need.
- Images that help, each with alt text.
- Natural links to related pages, with anchor text that says where they lead.
Search engines sometimes show a short answer or list at the top of the results, taken from a page. Nobody can force that. But a page that answers clearly in plain structure gives itself the best chance, and it is better for readers either way.
Check the structure with code
You cannot measure quality with a program, but you can measure structure. The checker below reads a page and reports nine simple facts: length, whether the keyword appears in the title, early on and in a subheading, how many subheadings there are, the longest paragraph, lists, internal links and images without alt text. We run it on Elena’s first draft and on her improved version. The output is real, and we counted the same facts a second way with a different tool.
from bs4 import BeautifulSoup
def grade(page, keyword):
soup = BeautifulSoup(page, "html.parser")
body = soup.body
words = body.get_text(" ").split()
paras = [len(p.get_text(" ").split()) for p in body.find_all("p")]
subs = [h.get_text().lower() for h in body.find_all("h2")]
links = [a for a in body.find_all("a", href=True) if a["href"].startswith("/")]
return {
"words": len(words),
"keyword in title": keyword in soup.title.get_text().lower(),
"keyword in first 50 words": keyword in " ".join(words[:50]).lower(),
"subheadings (h2)": len(subs),
"keyword in a subheading": any(keyword in s for s in subs),
"longest paragraph": max(paras),
"lists or tables": len(body.find_all(["ul", "ol", "table"])),
"internal links": len(links),
"images without alt": len([i for i in body.find_all("img") if not i.get("alt")]),
}
draft = """<html><head><title>Meal Prep</title></head><body>
<h1>Meal Prep</h1>
<p>Meal prep is when you cook food in advance and there are lots of ways to do it
and many people like it because it saves time during the week and also money and
you can make rice and chicken and vegetables and put them in boxes and eat them on
different days and it is good for people who work and also for students and families
and you can freeze some of it if you want to keep it longer.</p>
<img src="plan.jpg"></body></html>"""
better = """<html><head><title>Meal Prep for One: A Simple Weekly Plan</title></head><body>
<h1>Meal Prep for One: A Simple Weekly Plan</h1>
<p>Meal prep for one means cooking a few simple dishes once and eating them over
several days. This plan takes about two hours on a Sunday.</p>
<h2>What you need</h2>
<ul><li>Two or three airtight containers</li><li>One tray for the oven</li>
<li>A pan for rice or grains</li></ul>
<h2>The Sunday plan</h2>
<p>Cook one grain, one protein and one tray of vegetables. Mix and match them
through the week so meals do not feel repeated.</p>
<h2>Meal prep for one on a budget</h2>
<p>Buy in bulk and freeze extra portions. See our
<a href="/budget-meal-prep">budget plan</a> and the guide to
<a href="/meal-prep-containers">containers</a>.</p>
<img src="plan.jpg" alt="Three meal prep boxes on a table"></body></html>"""
kw = "meal prep for one"
a, b = grade(draft, kw), grade(better, kw)
print("check: draft -> better")
for k in a:
print(f"{k}: {a[k]} -> {b[k]}")
check: draft -> better
words: 83 -> 103
keyword in title: False -> True
keyword in first 50 words: False -> True
subheadings (h2): 0 -> 3
keyword in a subheading: False -> True
longest paragraph: 81 -> 26
lists or tables: 0 -> 1
internal links: 0 -> 2
images without alt: 1 -> 0
Compare the two columns. The draft has 83 words and the improved version 103, so length barely changed, yet almost everything else did. The keyword now appears in the title, in the first 50 words and in a subheading. There are 3 subheadings instead of none. The longest paragraph shrank from 81 words to 26. There is a list, two internal links and no image without alt text.
Notice what the checker cannot tell you. It cannot tell you that the plan in the improved version is actually good, or that the advice is right. A page can tick every box and still be dull or wrong. Use the checker as a tidy-up tool after you have written something worth reading, never as the goal.
Before you publish
- Read the article aloud. Fix anything that sounds clumsy or repeats itself.
- Check every fact, number and link. Add your name and a short note on who you are if readers would want to know.
- Write the title and meta description (lesson 4) and check the page address.
- Add internal links to and from the page, following your link plan.
- Preview on a phone. Then publish, and add the date to your notes.
Chasing green ticks. Stuffing the keyword into every subheading to pass a check makes the article worse. If a check fails and the page reads well, trust the reader over the checker.
Search engines have said they do not use a minimum word count. The two drafts here are short on purpose, to keep the demonstration readable. Real articles should be as long as the topic needs.
Practice for this lesson
Check what you learned
Five quick questions. Pick an answer and you will see straight away whether it is right and why.
What is the purpose of a brief?
- To replace the article
- To stop you wandering before you write
- To fool search engines
- To shorten the title
A brief fixes the keyword, reader, promise and outline before you start writing.
Where should the main answer appear?
- At the very end
- Only in the footer
- Hidden in an image
- In the first sentences
Answer first, then explain. Readers who find answers quickly stay and trust you.
Which change most improved the long paragraph?
- Writing it in capitals
- Making it shorter and splitting it
- Adding more keywords
- Moving it to the footer
Splitting long blocks into short paragraphs makes a page easier to skim, especially on phones.
What can the structure checker NOT tell you?
- How many subheadings there are
- Whether an image lacks alt
- How many links there are
- Whether the advice is good
It measures structure only. Quality needs a human reader.
What should you do if a check fails but the page reads well?
- Trust the reader over the checker
- Delete the page
- Repeat the keyword more
- Hide the text
Checks are a tidy-up tool. The goal is a helpful page.
Summary
- A short brief keeps the article focused on one reader and one promise.
- Answer first, then explain in short, clear sections.
- A checker can measure structure but not quality.
- Read aloud and verify facts before you publish.
Questions
How long should an SEO article be?
As long as the topic needs. There is no ideal word count. Compare with the best pages for your keyword and ask what they leave out.
Do I need an image in every article?
Not always, but helpful images such as photos, diagrams or screenshots make pages easier to understand. Always add alt text and keep the files small.
Should I put my keyword in every heading?
No. Use it where it reads naturally, perhaps in the title and one subheading. Forcing it everywhere makes the page worse.
