Source material
A column of values that means nothing without the heading it was under
A specification is the densest document any business publishes and the one most dependent on a single word at the top of it. Take fifteen attribute lines out of the middle of a spec sheet and they are true of a specific model, and they do not say which one. Attach them to the wrong model and every one of them is wrong, individually, precisely, and with a citation.
Why this one is harder than it looks
The model name governs the whole document and appears once. Everything below it is a dependent clause: the weight, the dimensions, the capacity, the power draw. A passage of attributes carries the values and not the subject, and a passage is matched by meaning, so a question naming a model can perfectly well pull a block of attributes that belongs to a different one.
Variants make this sharper rather than merely more likely. A range with three sizes, or two finishes, or a mains and a battery version, produces several near-identical blocks of attributes that differ in a couple of lines. Those blocks compete against each other for every question, they look almost the same, and the thing that distinguishes them is exactly the thing that tends not to be repeated inside each block.
Units and tolerances go missing in the other direction. A specification sheet is written for somebody who knows the convention, so numbers appear bare, or a units column at the top of a table governs a column of figures. Convert the table, split it, and the figures arrive without their units, at which point a figure is not an approximate answer, it is an unusable one.
Then there is the delivery problem. Specifications are very often published as a download rather than as a page, so a crawl of the site never reads them, because a link is not the linked file. A specification in a file that was exported as a graphic is worse again: a file is read page by page as text and text inside an image is not read at all, so a beautifully typeset sheet can contribute nothing whatsoever. And compatibility, which is the single most asked specification question, is usually left as an inference from a table when it needs to be a list of names.
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.
| The model name in every heading and every block | Not once at the top but in the section heading and again in the first line of each group of attributes. It looks redundant on the page and it is the only thing that keeps a passage attached to its subject. |
|---|---|
| One block per variant, with the difference named inside it | The size, the finish, the power option, written into the block rather than expressed as a column in a shared table. Two blocks that differ in one line each need that line to be unmissable, because everything else about them matches equally well. |
| Units on every value, and tolerances written out | In the value itself, not in a column header and not in a note at the foot of the table. Where a figure is nominal or has a tolerance, say so beside it, because a stated tolerance is a real answer and an implied one is a complaint. |
| A compatibility list naming things | What this works with, item by item, by name and by model. Not a table from which compatibility could be worked out. Somebody asking whether it fits their particular thing needs their particular thing to be a word in your document. |
| The specification present as page text, whatever else you publish | If you publish a downloadable sheet, publish the same content on the page too, or upload the file directly rather than relying on a crawl to follow a link to it. A specification that exists only behind a download link is a specification nobody indexed. |
The rewrite, in order
Repeat the model name until it looks excessive
Put it in the section heading. Put it in the first line under the heading. Put it in the caption of any table. If the sheet covers a range, put it in every row of the table as its own column rather than relying on a heading above the group.
The instinct against this is strong, because repetition looks unpolished to anybody reading top to bottom. The trade is straightforward: mild redundancy on the page against the elimination of the worst failure this document has, which is a set of precise values attributed to the wrong product.
Split variants into blocks rather than columns
A shared table with a column per variant is compact and it is the format that fails hardest, because a passage from it carries rows without their column identity. Write each variant as its own short block instead, with its own heading, repeating the attributes that are common.
In each block, lead with what makes it different. If the only difference is capacity, the first line after the heading should say the capacity. That line is what a question about the difference will match against, and it needs to be in the same passage as everything else the block asserts.
Write the units and the tolerance into the value
Go through every number and finish it. The unit, spelled the way a customer would write it rather than only as a symbol, since a symbol is a poor match for a typed question. The tolerance or the nominal qualifier where one applies. The condition a rating was measured under, where that matters, because a figure measured under one condition and quoted for another is a specification dispute waiting to happen.
This is also the moment to remove a units row or a units column, which is the classic case of meaning living in layout. A header cell saying millimetres governing eight figures below it is exactly the structure that does not survive being split.
Turn compatibility into an explicit list of names
This is the highest value section on most spec sheets and the one most often absent. Write what the product works with, by name: models, generations, sizes, standards, connectors, other products in your range. Then write what it does not work with, where that is a question you get.
Names are what make this work. A customer asks whether it fits a specific thing they own, and they type the name of that thing. If the name is not in your document, no amount of attribute data will produce the match, and the assistant will be right to say it does not know about a compatibility you could have simply listed.
What happens if you skip it
A precise specification confidently attributed to the wrong model
Somebody asks the dimensions of one product in a range. The retrieved passage is a block of attributes from the sheet, complete, exact, and belonging to the variant above or below the one they named, because the block did not carry a model name and the range shares almost all of its vocabulary.
The cost is specific to this document: somebody orders based on the figures, and a physical thing does not fit. Nobody involved will suspect a document structure problem, because the numbers were real numbers from a real sheet. This is the failure that repeating a model name six times prevents entirely.
Check it against this
Before you index it
- The model name appears in every heading and every attribute block
- Variants are separate blocks, each leading with what makes it different
- Every number carries its unit in the value itself
- Tolerances and measurement conditions are stated beside the figures
- Compatibility is a list of names, not something to be worked out
- The specification exists as page text, or the file itself was uploaded
- No part of the specification exists only inside an image
Questions
- We publish specifications as downloadable files. Is that a problem?
- Only if you rely on a crawl to reach them. A crawl reads pages, and a link to a file is not the file. Upload the files directly, which is supported, or publish the same content as page text. Do check that the file is real text rather than an exported graphic, because a page of image has nothing in it to read.
- Should we upload the full technical manual too?
- It is useful material and it competes with everything else you own, because a long manual produces a great many passages that all look technical. If you upload it, make sure the short specification exists as its own document too, so the concise answer has something to be retrieved from.
- Our specs are in a table on the product page. Is that enough?
- A table in a page is converted to a Markdown table, so it will be read. What determines whether it answers well is whether each row stands alone: the model in a column rather than in a heading, units in the values, and no merged cells doing structural work.
Keep reading
- The question this document answersWhat the visitor is really asking, and where an answer becomes a handover.
- How to write a pricing page an AI assistant can quote fromPrices that only exist in an interactive component are not in the text at all. How to publish pricing an assistant can quote without inventing.
- How to structure a shipping and delivery table an assistant can readA zone by service grid loses its meaning one row at a time. How to write delivery information that survives being split into passages.
- Publishing opening hours and locations an assistant answers correctlyThe easiest question to get wrong. Hours in an image, five stale copies, and kitchen times that differ from door times, all fixed at the source.
- 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.