Read the Metadata Before You Read the Spec

Mostafa Dhouib·9 min read

Read the Metadata Before You Read the Spec

The short answer. A specification you receive carries two documents. One is the text, which has been edited, reviewed and softened. The other is forensic and was not edited, because nobody knew it was there. The rendering engine and version tell you what tool produced the file and therefore what process produced it. Route names in a module list tell you which framework the design was drawn against. Word frequency tells you what the organisation actually cares about, as opposed to what it listed first: one specification we received used the word audit 73 times. Reading the file as an artefact before reading it as prose changes what questions you ask in the first meeting.

A tender document or a requirements specification arrives and the instinct is to start reading it from the beginning.

That is the right thing to do second. The document has been through revision and internal review, so the prose reflects what the organisation decided to say. The artefact around the prose reflects what the organisation did, and nobody reviewed that.

What the producing tool tells you

Open the file's properties before the file's content.

Documents carry the identity and version of whatever generated them. A specification exported from a word processor is a different animal from one generated by a document assembly tool, which is different again from one produced by a procurement platform.

What you learn is about process rather than technology.

A document produced by an export from a tracking or procurement system means the requirements are stored somewhere structured, and that store is the real source. The document is a rendering of it. Asking for access to the underlying list is both possible and far more useful than negotiating over the rendering, and the question signals that you understand how their organisation works.

A generator version several years old tells you the template and the process are old, and that the structure you are reading may be inherited from a previous unrelated project. Sections that feel irrelevant probably are, and you can ask directly rather than diligently costing requirements nobody wants.

Multiple different producers across a document set indicates the pack was assembled from several sources, likely by different teams, and the parts have not been reconciled. That is where contradictions live, and knowing where to look for them is worth a week.

Creation and modification timestamps separate the sections written for this project from the ones carried forward. A document created shortly before issue, containing sections authored much earlier, is a compilation.

None of this is secret and none of it requires anything clever. It requires looking.

What route names reveal

The most useful single artefact in a specification is a module or screen list, because it is almost never written from scratch.

Someone built it from a system they had in front of them. The naming conventions survive that transfer, and naming conventions are framework-specific.

A module list whose entries follow a controller-and-action naming pattern was taken from a framework that organises code that way. A list of screens named with a resource-and-verb structure came from somewhere that generates routes from resources. A list with segments that look like a particular admin panel's default scaffolding came from that scaffolding.

Why this matters practically.

The specification describes an existing implementation, not a desired one. If the module list is a transcription of a working system's routes, then the requirement is to reproduce that system. The gaps in the specification are the gaps in the transcription, and the real specification is the running system.

It tells you what the previous supplier used. Which tells you what the organisation's staff are familiar with, what their internal documentation assumes, and what the integration points will look like.

It tells you where the specification will be thin. A route list captures what has a screen. Scheduled work, background processing and integrations do not appear as routes, so a specification derived from routes will be close to silent on exactly the parts that carry the most risk.

It tells you whether the author was technical. A list with framework naming intact was assembled by someone reading code or configuration. A list with plain business language was written by someone describing the business. Those two authors need different conversations and will give you different quality of answers.

Word frequency tells you the real priority

The ranked list of requirements tells you what the organisation decided to prioritise in a meeting. Word frequency across the whole document tells you what it is preoccupied with.

Those differ, and the second one is more reliable, because repetition is not strategic. It is the residue of many people writing many sections while thinking about the same thing.

One specification we received used the word audit 73 times. It appeared in sections about reporting, about user management, about data retention, about integration, about permissions. The functional requirements list did not put auditability at the top. The document could not stop talking about it.

That number changes the engagement. It says the real acceptance criterion is traceability, that someone has been burned by not being able to answer a question about who changed what, and that a system which delivers every listed feature and cannot reconstruct history will be rejected. It also says the architecture decision that matters most is whether records are immutable and append-only, which is the sort of decision that is cheap at design time and close to impossible to retrofit.

Running the count is trivial. Extract the text, normalise case, strip common words, and look at what is left in rank order. What you are looking for is the gap between the ranked requirements and the ranked vocabulary.

Two other patterns in the same analysis.

Hedging density. Sections heavy with conditional language are the sections where the organisation has not decided. Those are the ones that will change after signature, and they should be priced as unknowns rather than as requirements.

Specificity asymmetry. One area described at field level while another is described in a paragraph tells you where the institutional knowledge sits. The vague area is not simpler. It is unowned.

How to use it without being strange about it

This is a preparation technique, not a conversational one. Nobody wants to hear that you examined their document properties.

What it produces is a short list of better questions. Rather than asking what their priorities are, which gets you the ranked list you already have, you ask whether there is a structured requirements store you could read. You ask who wrote the module list and what they were looking at. You ask what happened the last time someone needed to establish who changed a record.

Each of those questions comes from the artefact and lands as competence rather than as analysis.

The honest limit

Metadata lies in ordinary ways, and most of them are boring.

A document converted between formats carries the converter's identity rather than the original author's tool. A file passed through a document management system is often stamped with that system's details, erasing everything upstream. Author fields frequently contain the name of whoever holds the licence rather than whoever wrote the content, and templates copied between organisations carry the wrong provenance entirely.

Word frequency is also a weaker signal on short documents and on documents assembled from boilerplate, where repetition reflects a template rather than a preoccupation. A compliance section copied from a standard will repeat its own vocabulary regardless of what the client thinks.

Most importantly, every inference here is a hypothesis to test in conversation, not a conclusion to act on. The technique's value is in generating sharper questions early. A supplier who treats a metadata reading as established fact and designs against it has replaced one unverified specification with another.

FAQ

What can document metadata tell you about a specification? The producing tool and its version, which indicate the process behind the document rather than just the technology. An export from a procurement or tracking system means the real requirements live in a structured store you can ask for. Several different producers across one pack means it was assembled from multiple teams without reconciliation, which is where contradictions concentrate.

Why do route or module names in a specification matter? Because that list is almost never written from scratch. Framework-specific naming conventions survive transcription, so a controller-and-action pattern or a resource-and-verb structure reveals which framework the author was reading. That usually means the specification describes an existing implementation rather than a desired one, and the running system is the real specification.

What does word frequency reveal that a requirements list does not? What the organisation is preoccupied with, rather than what it decided to rank in a meeting. Repetition is not strategic, it is the residue of many people writing while thinking about the same concern. One specification used the word audit 73 times across sections on reporting, permissions, retention and integration, while the ranked requirements did not put auditability near the top.

How would you act on a document that repeats audit constantly? By treating traceability as the real acceptance criterion. Someone in that organisation has been unable to answer a question about who changed what, and a system delivering every listed feature without reconstructable history will be rejected. The design consequence is deciding early whether records are immutable and append-only, because that is cheap up front and close to impossible to retrofit.

Where will a route-derived specification be weakest? On everything without a screen. Scheduled work, background processing, batch jobs and integrations do not appear as routes, so a specification transcribed from a route list is close to silent on exactly the areas that carry the most delivery risk. That silence looks like simplicity and is usually absence of ownership.

When does document forensics mislead you? Often, in mundane ways. Format conversion replaces the original tool's identity with the converter's, document management systems stamp their own details over everything upstream, and author fields commonly name a licence holder rather than a writer. Word frequency is also weak on short documents and on boilerplate, where repetition reflects a template. Every inference is a question to ask, not a fact to design against.