Write down what you could not find

A design document asserts things its format never earned. The fix is structural: a numbered section for what you could not establish, and attribution by source type in the body rather than only in the references.

Write down what you could not find

Nine months after you hand over a design, somebody reads a number out of it in a steering meeting. It is your number, in your table, under your name, and the room is making a decision on it.

And you cannot remember whether you verified that number or whether it was simply the most reasonable thing available on the Tuesday afternoon you wrote that section.

That gap, between what a document asserts and what its author actually knew when they wrote it, is the most common defect in enterprise design work. Almost nobody treats it as a defect.

Format is what makes it dangerous

In conversation you hedge without thinking about it. You say "I think it is around thirty addresses, I would check that". The listener hears the hedge, files the number as soft, and moves on. Nothing is lost.

A design document strips that out. Not deliberately. It is just that a table cell cannot say "probably", a numbered decision implies somebody decided, and a justification field implies somebody justified. The format does the asserting for you, whether or not you meant it to.

So the same uncertain figure, moved from a conversation into a document, arrives with an authority you never gave it. Six months later it is in a steering pack, then in a business case, and by then it has been repeated enough times that challenging it looks like obstruction.

The thing to notice
Nobody lied. The figure was reasonable when it was written and it may well still be correct. The defect is that the document does not distinguish between the lines the author would defend and the lines the author would check, and the reader has no way to tell them apart.

How it actually happens

It is rarely carelessness. It is almost always speed plus a document structure that will not let you stop.

You are writing the addressing section. The vendor page gives you the architecture but not the number. A community post gives you a range and it looks right. You need a sentence in that paragraph, because the section does not work with a hole in it, and the review is Thursday. So you write the sentence and intend to come back.

You do not come back. Nobody comes back. And the sentence you wrote reads exactly like the three sentences either side of it, which came off a vendor page you read twice.

I have done this. Everybody who writes designs for a living has done this. The fix is not to try harder, because trying harder is what you were already doing at eleven at night on the Wednesday. The fix is structural.

Give the document somewhere to put what you do not know

Add a section at the end for open items. Not a caveat paragraph, not a line in the introduction that nobody reads. A numbered section with the same visual weight as the design decisions, because it carries the same weight in practice.

Each entry gets an identifier, a statement of what could not be established, and a reason it matters. Where you can, name who has to answer it.

E-01
Supported number of integrated standalone instances per management instance, and the effect of integration load on management plane sizing. This is a sizing input, so it is a design gate.
E-02
Capability delta between an integrated instance and a converted one, stated by the vendor rather than inferred from feature lists.
E-03
Minimum privilege set required by the integration service account on the target.

Three things happen once that section exists.

The first is immediate. You now have somewhere to put the uncertainty, so you stop smoothing it into the body text. The pressure that produced the confident sentence is gone, because the document has a legitimate place for "I could not establish this".

The second is that the reader can calibrate. Somebody who disagrees with you knows which lines to push on. Somebody who agrees with you knows which lines not to build a programme on. Both of those are better outcomes than a uniformly confident document.

The third takes a few months to show up. When the figure gets challenged in month nine, you can answer in one sentence instead of trying to reconstruct what you knew. Either it is in the open items and was never a commitment, or it is not and you stand behind it.

The second convention, which is smaller and matters nearly as much

Attribute by type in the body, not only in the reference list.

A references section at the back tells a reader where you looked. It does not tell them which specific claim came from where, and nobody cross-references a design document while reading it. So when a figure comes from community material rather than a vendor page, say so in the sentence that uses it.

Something like: this figure comes from community documentation rather than a vendor page, so treat it as a planning number and verify before build.

It costs you a clause. It buys the reader the ability to weight the number correctly at the moment they encounter it, which is the only moment that matters.

"Does this not make me look like I do not know?"

This is the real objection, and it is usually unspoken. There is a worry that marking gaps reads as not having done the work, particularly if you are the external party and somebody is paying for the document.

My experience is the opposite, and reasonably strongly so.

What reviewers do
Senior reviewers probe for the soft spots first. A document that marks its own saves them the search, and the ones I have handed over this way get a faster and better review, not a harsher one.
What customers do
The open items list becomes their agenda with their account team. You have handed them a task list they would otherwise have had to work out themselves, usually by being surprised.
What happens later
The author who marked a gap and was later proven right on everything else is trusted more, not less. The author whose unmarked figure turned out to be wrong spends the next two years being asked where numbers came from.

There is a limit to this, obviously. A document that is mostly open items is not a design, it is a research proposal, and saying so is more honest than dressing it up. But that failure is visible. The one it replaces is not.

What it looks like in practice

I published four design documents last week for VMware Cloud Foundation 9.1.1. Each one ends with a list of things I could not establish from public material: supported instance counts, a capability delta, resource figures for a deployment profile, entitlement scope.

I could have filled every one of those in with something plausible. The documents would have read as more complete and almost nobody would have checked. That is precisely why I did not, because "nobody will check" is the condition under which a wrong number survives longest.

Where a figure came from community material rather than a vendor page, the body text says so. Two of them do. They are both planning figures that I would want confirmed before anyone orders hardware against them.

If you take nothing else from this
The test for a design document is not whether it reads as confident. It is whether a reader can tell, without asking you, which lines you would defend and which lines you would go and check. If they cannot tell, the document is doing work it has not earned.

Where to start

Open the last design you wrote. Go to the section you wrote fastest, which you will remember.

Read it for figures rather than for argument. For each one, ask whether you could name the source right now without looking. The ones where the answer is no are your first open items, and there will be more of them than you expect.

Then decide whether to go and verify them or to mark them. Either is fine. Leaving them as they are is the only option that is not.

Related: the management plane post and the fleet operations post, both of which carry figures I have marked this way, and the design guides repository if you want to see the convention applied end to end.

The clearest worked example on this site is will the hardware come with you, which ends with four open items rather than four confident sentences.

More on VCF

This is one of the VCF pieces here. The rest are grouped by problem rather than by date on the VCF index, which is the fastest way to find the one you actually need.

Eight free planning tools run in your browser, with nothing sent anywhere. They are all on the tools page, from Estate Readiness Triage to the Restore Evidence Check.

Read next