Source material
A guide is a sequence, and what comes back is one step from the middle
An onboarding guide is the document owners reach for first and the one that disappoints them fastest. It is usually accurate, usually well written, and structurally the worst possible shape for a retrieval system, because everything that makes it readable end to end is what breaks it when a single passage is pulled out and handed to a model on its own.
Why this one is harder than it looks
Almost every onboarding guide is written by somebody who already understands the product, for a reader the writer imagines is halfway through the setup. That is the wrong reader twice over. It is the wrong reader for a new customer, and it is catastrophically the wrong reader for a passage extracted from position eleven of a document, because the assumed context was never on the page to begin with. Phrases like the workspace, your project, this screen and the settings above all point at something the passage cannot see.
Then there is the step that assumes the step above it. Click Save is a complete instruction to somebody who has just read the previous four lines and a meaningless one to anybody else. Save what, on which screen, having done what first. When a question about setup matches that passage by meaning, and it will, the assistant answers with a step and presents it as the procedure, because from where it is standing that is what a procedure looks like.
Prerequisites are almost always in the wrong place. Guides tend to end with a note saying that this requires an administrator seat, or that the domain has to be verified first, or that it only works on a paid plan. That note becomes its own passage. The steps become other passages. Nothing links them, so the question how do I invite my team retrieves the steps and never the condition that makes the steps possible, and the customer follows instructions that were never going to work for them.
Screenshots are the quiet one. A crawled page gives up the alt text at best and usually nothing. An uploaded document is read as text, so an image contributes nothing at all, however much information is inside it. If the exact name of a menu item, the position of a toggle or the wording of a confirmation dialogue appears only inside a picture, the assistant does not have it, and it will happily answer around the gap with something vaguer than the truth.
What it has to contain
Structure rather than wording. A passage pulled out of this document has to stand on its own, because that is the only form in which it will ever be read.
| A scope sentence at the top of every section | One sentence naming who this part is for and what state their account is in when they start it. This is the sentence that survives extraction, so it has to carry the context the rest of the section assumes. |
|---|---|
| Prerequisites inside the step that needs them | Not a footer, not a callout at the end. If the third step requires an administrator seat, the third step says so in its own words, because a callout at the bottom of the page is a separate passage from the step. |
| A screen name and an object in every step | Every instruction names where the reader is and what they are acting on. Open Settings, then Team, then select Invite member. Never click Save, never choose the second option. |
| The end state, written out | What the reader should be looking at when the section is finished, described concretely enough that somebody can check it. This is what turns a fragment into something a person can verify without the rest of the guide. |
| Screenshot content restated in prose | Every menu name, field label, button wording and error string that appears in an image also appears in the text near it. The image can stay for the humans. The text is the part that gets indexed. |
The rewrite, in order
Move each prerequisite into the sentence that depends on it
Go through the guide and find every condition stated anywhere other than in the step it governs. Plan requirements, permission levels, a verified domain, an installed integration, a browser limitation. These usually live in a note at the top or a caveat at the bottom, and both positions put them in a different passage from the instruction they qualify.
Rewrite each one into the step. Not as a nested note under the step, which often extracts separately, but inside the instruction itself: to invite a team member you need an administrator seat, so if the Invite button is greyed out that is why. The sentence is longer and slightly repetitive across a document read end to end. That repetition is the point, because passages are read alone.
Where a prerequisite governs the whole document rather than one step, put it in the opening scope sentence and repeat it in the first step that would fail without it. Two mentions is not sloppy writing here. It is two chances for the right passage to carry the condition.
Give every step a screen and an object
Read each numbered step and ask whether somebody dropped into it with no other information could act on it. Most cannot, and the fix is nearly always the same two additions: name the screen the reader is on, and name the thing they are acting on rather than pointing at it with a pronoun or a position.
This means the same screen name appears in five consecutive steps, which looks clumsy to an editor. Accept it. A sequence of steps that each name their own location is a sequence where any single step still tells the truth on its own, and that is exactly the condition the document is being rewritten for.
Where a step genuinely cannot stand alone, because it is the third of three actions in one dialogue, merge it upward. Three dependent instructions in one passage is better than three passages that each need the others. Ordering only survives inside a passage, never between passages.
Split by outcome, not by chapter
A single long guide called Getting Started is one long sequence, and a retrieval system will keep handing back middles of it. Break it into pages that each cover one thing a person might want to have done: connecting a domain, inviting a team, importing existing records, setting up billing.
Each of those pages opens with what it achieves and closes with how you know it worked. Cross-link them in a fixed order for people reading in sequence, but write each one so that arriving at it cold is a reasonable experience. The ordering problem does not go away, it moves up a level, where it does far less harm: a customer sent to the wrong page can tell immediately, whereas a customer given the wrong step cannot.
This also fixes the most annoying version of the failure, where a question about the last part of setup retrieves the first part because the first part is longer and uses more general words. Separate pages compete on their own subject rather than on their share of a very long document.
Write out what the pictures are saying
Walk the guide and list every screenshot. For each one, ask what a reader would learn from it that is not in the surrounding text. Menu labels, the exact wording of a button, the name of a field, the text of a confirmation, the location of a toggle relative to other controls. That list is what is currently invisible.
Put every item on the list into the prose. Not into alt text alone, which is thin and often unwritten, and not into a caption that will be extracted separately from the step it belongs to. Into the sentence of the step itself, so that the passage carrying the instruction also carries the label the reader has to look for.
Annotated screenshots with numbered callouts are the worst offenders, because the numbers in the image refer to a legend that sits somewhere else. Either write the legend into the step text or drop the numbering and describe the sequence in words.
What happens if you skip it
The answer that is a step from the middle
The characteristic wrong answer from an unmodified onboarding guide is short, confident and correct in isolation. A customer asks how to get their team set up, and what comes back is one instruction from partway through the sequence: open the members list and choose Invite. It cites its passage honestly. The passage really does say that.
What it does not say is that the domain has to be verified first, that the person asking is on a plan where the button does not appear, or that three earlier steps put the account into the state where the instruction makes sense. The customer follows it, finds nothing where they were told to look, and now believes the product is broken rather than that they are in the wrong place.
The cost is specific to onboarding: this is the first thing a new customer does, and the answer arrives at the moment they are deciding whether the product is going to be difficult. A vague answer here is survivable. A precise answer to a step they cannot reach yet is worse than silence, because it sends them looking for something that is not there.
Check it against this
Before you index it
- Every section opens with who it is for and what state they are in
- No step contains this, that, above, or the previous screen
- Every prerequisite sits inside the step it governs
- Every step names a screen and names an object
- Nothing important appears only inside a screenshot
- Each outcome is its own page with its own end state
- Any single step, read alone, is still honest
Questions
- Do I have to repeat the same prerequisite on several pages?
- Yes, and it is the right call. Passages are read one at a time, so a condition stated once at the top of a long document is absent from every passage except the one it happens to land in. Repetition that looks redundant to a human reader is what keeps each fragment truthful.
- Should I delete the screenshots?
- No. Keep them for the people reading the page, because a picture of the screen is genuinely faster for a human than a description of it. Just stop letting them be the only place a label exists. The rule is not fewer images, it is no information that lives only in an image.
- My guide is one long page and splitting it is a big job. Is there a cheaper fix?
- Yes, in this order: add a scope sentence to every section heading, move the prerequisites into their steps, and remove positional references from step text. That is most of the benefit for a fraction of the work. Splitting by outcome is the improvement you make afterwards, when you can see which sections people actually ask about.
Keep reading
- The question this document answersWhat the visitor is really asking, and where an answer becomes a handover.
- How to write a troubleshooting article that gets found by the error messagePeople paste the error text. If your article never quotes it verbatim, it is invisible. How to restructure symptoms, causes and decision trees.
- How to make an API reference answerable and not just completeGenerated reference pages are mostly boilerplate, which makes every passage look alike. Fix the tables, the examples and the version paths.
- Why indexing your changelog makes the assistant describe the pastRelease notes record moments. Questions are about now. How to stop an assistant quoting a change that was later reverted or superseded.
- Every kind of source materialWhat to feed an assistant, and the surgery each document needs first.
Try it on your own material
Upload a document or point it at your site, paste one line of HTML, then ask it something only your business could answer.