How-To Guides vs Docs vs Blog: Information Architecture

A site that explains technical products tends to grow three kinds of page without anyone deciding to: documentation, blog posts and tutorials. Readers cannot tell which is which, and neither can the search engines. The same question ends up answered three times with three different commands, and the oldest one ranks. This post sets out how we separate them, what each one is for, and the small set of rules that keeps them from competing.

The three jobs

Docs say how the product works. They are reference: every option, every field, every limit, in a stable structure. They are written for someone who already decided to use the thing. They change when the product changes, and they should be exactly right about the product and silent about everything else.

How-to guides take a person through a task. They are procedural: an outcome, prerequisites, numbered steps, what you should see, what to do when it breaks. They may involve several tools, including ones that are not yours. They change when the tools change, so each one carries a date saying when its commands were last checked.

Blog posts take a position or report something. They are argument and analysis: a comparison, a launch, a lesson learned, a method. They are tied to a date and are allowed to age. A reader finishes one with an opinion or a decision, not with a working system.

A fourth kind, the explainer ("what is X"), sits between them. It answers a definition question and hands over to a how-to or to docs. We keep explainers as landing or topic pages, not as blog posts, because a definition should not age.

Which one do I write?

Ask what the reader wants to end up with.

If you cannot choose, the page is probably trying to do two jobs. Split it.

The rules that keep them from competing

1. One owner per question. For each question you want to rank for, name one page that answers it. Other pages link to the owner and do not answer it again. We track this in a typed topic map: topic, intent, owning route. A script reports where two pages seem to compete and where an intent has no owner.
2. The how-to owns the commands. Docs and blog posts that need a command link to the guide and do not copy it. When a command changes, you change it once.
3. The blog owns the opinion. A guide says "do this"; the post that argues why belongs on the blog, linked from the guide. This keeps the guide short and the opinion honest, since it is labelled as one.
4. Docs own the product. A guide that depends on product behaviour links to the doc page for it. If you are writing a product claim into a guide, check that the docs say the same thing, and if they do not, one of them is wrong.
5. Dates mean different things. On a blog post the date is when it was published and is allowed to stand. On a guide it is when the commands were last verified, and it should move only when you have re-checked. On docs it is the product version.
6. No orphans. Every guide is linked from the hub, from at least one related guide and from the explainer for its topic. A coverage script lists pages with no inbound links so they can be fixed.

Flat URLs and what they cost

We put the guides at flat paths such as /how-to-run-llms-locally rather than /how-to/run-llms-locally, because the question is the page and the path reads like it. The trade-off is that a flat path has no folder for the hub, so the hub at /how-to has to list every guide and each guide has to link back to it. The pages are thin files that import typed data, which keeps the template shared and the URLs exact. A catch-all or dynamic route would have hidden the paths from the file system and made it harder to check for clashes with existing routes.

Whichever pattern you choose, treat the URL as permanent. Do not put a year or a version in it. If the guide is replaced, redirect the old URL.

One source of truth, several outputs

The failure mode of a content set is drift: the page says one thing, the schema says another, the downloadable copy says a third. We avoid it by writing each guide once, as a typed record, and generating everything from it:

• the web page, with a table of contents, copyable commands and a troubleshooting table;
• the JSON-LD (HowTo, FAQPage, BreadcrumbList, Article);
• a markdown copy at /how-to/<slug>.md;
• an entry in /how-to/index.json, which a coding agent can read to find the right guide;
• the listing in llms.txt.

A validator runs over the record before outputs are written. It checks title and description length, that there are enough steps, sources and troubleshooting rows, that every internal link points to a page that exists, and that banned phrasing (invented certification claims, for example) is not present. If the record fails, nothing is written.

Mistakes we have seen, and made

• The tutorial that is really a pitch. A guide whose every step ends in the product's own button is a sales page with numbers on it. Readers notice, and so do engines that compare it with the neutral pages around it. Keep the product out of the steps unless the step needs it, and put what you offer in one clearly marked block at the end.
• The blog post that is really docs. A launch post that lists every parameter ages into an out-of-date reference nobody maintains. Put the parameters in docs and leave the post with the story.
• The guide with no date. If a reader cannot tell whether a command was checked last week or two years ago, they assume the worst. Show the verification date.
• Three copies of the same command. Someone updates one. Link to the owner instead.
• A hub that is only a list of titles. Group guides by what the reader is trying to do (build, deploy, validate, govern, secure, comply, operate), show difficulty and time, and let people filter. A flat list of twenty-six titles is a table of contents nobody reads.
• No way to ask. A visible "request a how-to" link on the hub tells you which questions people could not find answered. It is the cheapest research you can run.

Where product docs and guides meet

Our product pages describe what the platform is designed to let an organisation do. The guides do not depend on them: each guide works with open tools, and the "How Swfte can help" block at the end is optional and says plainly what is and is not available. For example, our guide on creating your own local model states that Swfte does not offer managed fine-tuning. That kind of limit belongs in a guide, where a reader is deciding what to do, and the product page can say what the platform is for.

A quick audit you can run

1. List the 20 questions you most want to be found for.
2. For each, find the pages that answer it. If there are two or more, pick the owner and edit the others to link to it.
3. If there are none, decide which type of page it should be, using the table above.
4. Check every guide for a visible verification date and a sources list.
5. Check that every command appears in exactly one place.
6. Find pages that nothing links to.

Our own run of steps 2 and 6 is automated: pnpm seo:coverage reads the topic map and the keyword data, assigns keywords to the pages that cover them, and writes a report of intent gaps, competing pages and unlinked pages. It uses a token-matching heuristic, so it finds candidates and a person decides. You can browse the guides it protects from the how-to hub, and see the research behind the structure in how people and LLMs search for AI infrastructure answers.