Should Contracted Development Specs Stay in Excel? — Choosing the Right Format for Deliverables

“We received a revised spec, but had no idea what had actually changed, and stamped it as accepted anyway.”

“When we went to commission a modification, the Excel spec we’d been delivered turned out to be nothing like the current screens.”

“The development company sent us a spec written in Excel graph-paper style — is this actually normal?”

When you outsource system development, the specification and design documents get delivered alongside the program. In Japanese contracted development, these documents are extremely often built in Excel, frequently written in what’s known as “Excel graph paper” — a style that chops cells into tiny squares and treats the sheet like manuscript paper.

There’s no shortage of criticism of Excel graph paper on the internet, but most of it is about how awkward it is as an internal document within a development team. This article takes a different angle: it focuses specifically on the specification delivered to the client in contracted development, and works through what’s wrong with it and what format to choose, in the practical contract-management language of acceptance testing, specification changes, and maintenance. The aim is content useful to both the client commissioning the work and the development company delivering it.

1. The Bottom Line First

Let’s start with the key points.

• Choose the format of a delivered spec not by “is it easy to write during development” but by “can the client review it,” “can it withstand acceptance testing,” “can specification-change diffs be shared,” and “will it still be usable in maintenance years from now.”
• The conclusion isn’t “abandon Excel” — it’s “abandon graph paper and put each format back where it belongs”: prose in Word, tables in Excel’s own proper tables, diagrams in a diagramming tool, and a record of agreement in PDF.
• Before debating format, settle which documents count as deliverables and whether you’ll receive an editable original in the contract itself (specifying deliverables in the individual agreement).

Putting the recommended format by document type into a decision table looks like this.

Here’s why, one point at a time.

2. What’s Wrong With an Excel Graph-Paper Spec as a Deliverable

Let me be clear up front: Excel the software isn’t the villain here. As a tool for spreadsheets and tabular lists, Excel is excellent, and as covered later, it’s the right answer for things like field-definition documents. The problem is cramming prose, diagrams, and tables — things with fundamentally different natures — all into “graph paper.”

For an internal company document, this is a problem that only inconveniences the people who wrote it. But once it’s a deliverable, the story changes, because a spec is a deliverable the client pays for, it’s the subject of acceptance testing, and it’s an asset that gets used for years afterward. Viewed as a deliverable, Excel graph paper has the following problems.

2.1 It Can’t Be Fully Reviewed at Acceptance Testing

Excel graph paper has nothing resembling Word’s practical change-tracking mechanism. To be precise, Microsoft 365’s co-authoring environment does have a history of cell changes (“Show Changes” or version history), and tools like Spreadsheet Compare exist for comparing workbooks. But what those can track is mostly cell values and formulas; they don’t cover the text inside the shapes and text boxes that graph-paper documents make heavy use of, and in a delivery workflow built around emailing files back and forth, co-authoring history doesn’t function at all to begin with.

In the end, when the client receives a revision that reflects their review comments, they have to hunt for “what actually changed” by eye. Re-reading dozens of sheets in full every single time isn’t realistic, so in practice, the acceptance stamp gets pressed on a basis of “it’s probably been fixed.”

This is acceptance testing in name only. Acceptance testing is the procedure of “confirming a deliverable matches the agreed content and accepting it”; once that becomes hollow, a problem discovered later turns into a pointless argument — “you already signed off on acceptance,” versus “no, it wasn’t delivered in a form we could actually verify.”

2.2 No Record of Agreement Survives a Spec Change

Specifications always change partway through development. When the document is Excel graph paper, the back-and-forth over those changes tends to turn into “a pile of file copies.” Plenty of people will recognize a file name like spec_v2_final_revised(2).xlsx.

The problem is that there’s no way to later identify which version “both sides actually agreed on.” When there’s a disagreement over additional cost or a deadline, the agreed document is what serves as the basis for resolving it. If it’s unclear which document that even is, it turns into a he-said-she-said standoff.

2.3 It Drifts From the Implementation During Maintenance

Because a graph-paper document is expensive to update, it gradually stops getting updated as modifications happen after delivery. Nobody wants to touch it for fear of breaking the layout; text inside shapes doesn’t show up in search, so fixes get missed — pile that up, and a few years later you end up with “a spec exists, but nobody knows whether it matches reality anymore.”

The bill for that state comes due at the next modification. If the document can’t be trusted, you have to start over by investigating the real thing — the running system and the source code — and that effort gets tacked onto the estimate. Letting a document go unmaintained comes back to bite you as higher future modification costs.

2.4 The Client Can’t Actually Make Use of It

A layout built for printing is hard to read on screen. And because the content is scattered across a large number of sheets and shapes, full-text search doesn’t work well, so finding “where was that requirement written down” takes time. It’s also hard for the client to reuse it — appending operational notes, repurposing it for an internal presentation — so a document they paid good money for tends to end up merely “sitting in storage.”

3. The Contractual Angle — a Spec Is a “Deliverable”

Before getting into format, let’s step up a level. A specification or design document becomes a contractual deliverable, on the same footing as the program itself, only by being defined as a deliverable in the contract. Put the other way around, a document not specified in the contract isn’t necessarily something you’re entitled to receive at all. IPA’s Model Transactions and Contracts for Information Systems is likewise structured around specifying deliverables in the individual agreement and defining the method and period for acceptance testing. The overall shape of that model contract is explained in a separate article, How Should You Structure a Contract for Contracted Development and Operations & Maintenance — Learning to Choose Between Quasi-Mandate and Contract-for-Work From IPA’s “Model Transactions and Contracts”.

In other words, the debate over Excel versus Word only means anything once the following foundation is settled.

• Which documents are deliverables: list them at the level of specific document names, not as “a full set of documentation.”
• What format you receive them in: does it include an editable original (a Word or Excel file)? PDF-only causes trouble during maintenance.
• The acceptance-testing method: what has to be confirmed before accepting it? How are diffs in a revision shown?
• How copyright and secondary use are handled: can the client copy or modify it internally? Can the document be handed over if maintenance is ever commissioned to a different company in the future?

If this isn’t settled in the contract, no matter how polished a format you pick, you’ll end up arguing over whether that document was even in scope for delivery in the first place. For how to get organized before placing an order, see Things Worth Sorting Out Before Outsourcing Windows App Development as well.

4. Deliverable Format Options — Comparing by “Does It Actually Work as a Deliverable”

Once the foundation is settled, choose the format. As stated at the top, there are four evaluation axes: how readable it is for the client, how easy it is to review and accept, how well spec-change diffs can be managed, and how well it holds up during the maintenance phase.

Some notes on each.

4.1 Word — the First Choice for Prose-Driven Specs

A document that “speaks in prose” — an overview design document, a description of a business flow — is naturally suited to a word processor. Word comes with everything a deliverable document needs, right out of the box.

• Heading styles and an automatic table of contents: the document’s structure becomes clear, and you can jump from the table of contents straight to the section you want.
• Track changes (the review feature): what changed in a revision shows up in red, right on the page. This is a world apart in how effective review and acceptance testing actually are.
• Comments: the client’s feedback and the responses to it stay attached to the document itself.
• Compare Documents: you can display the diff between two versions even after the fact.

The client needs no special tool and no learning curve, and it passes as a deliverable format as-is — a significant practical advantage.

The catch is that building a document that only looks tidy without ever using actual styles falls into the same hole — you could call it Word graph paper. Use heading styles for headings, and formatting settings rather than repeated spaces for layout. And the “which is the latest version” problem can still happen with Word, so pair it with the version-management practice covered later.

4.2 Bring Excel Back to Being a “Genuine Table”

Documents like a screen field-definition sheet, a code list, or a permission matrix are inherently tables. Writing these in Word is, if anything, inconvenient — Excel is the right answer. But use it as a genuine table you can treat as data, not as graph paper.

• One row per record, one column per attribute. Put only one table on each sheet.
• Don’t build layout with merged cells. Headers go in a single top row.
• Don’t break the data structure for the sake of how it looks printed (handle print formatting through a different means).

Built this way, the document can be handled mechanically during maintenance. Reuse cases like cross-checking field definitions against the actual database schema, or using the list directly as the basis for test cases, start working, which in turn makes the whole business of “checking whether the document has drifted from the implementation” easier.

4.3 PDF — the Format for Freezing an “Agreed Version”

PDF’s not being easy to edit is both a drawback and an advantage. It disqualifies itself as the original of a spec, but it’s well suited as a snapshot of the version that passed acceptance testing, or the version agreed on for a spec change. Because it can’t get accidentally rewritten, it functions as a record of “this is what we agreed on, at this point.”

Strictly speaking, though, a PDF can still be recreated. Its power as a record comes not from the PDF format itself but from both sides holding onto the same file, so pair it with a practice such as sending it by email and keeping the send record, or having both parties store it in their own environment. If you need it to hold up as evidence in an actual dispute, adding a digital signature or a timestamp is also an option.

There’s one more simple principle: PDF should always come paired with an editable original. Delivering PDF alone narrows the client’s future options — using it internally, or commissioning maintenance to another company.

4.4 Keep the Source in Markdown + Git, and Deliver Generated Word / PDF

On the development company’s side, it’s become increasingly common in recent years to write specs in Markdown and version them in the same Git repository as the source code. This gives you line-level diffs, lets you review documents through the same mechanism as a code review, and keeps the history of every change as history (that’s plenty for day-to-day development record-keeping, but if you need it to stand up as evidence for an audit or a dispute, you’ll separately need a practice that prohibits rewriting history).

None of this requires asking the client to use Git. Manage the source in Markdown, and generate Word or PDF for delivery with a conversion tool such as Pandoc, and the client just receives Word/PDF as before, nothing different from what they’re used to. This lets you have both the development side’s management efficiency and the client side’s readability.

The catch is making “which side is the source of truth” explicit in the contract. If the client edits the generated Word file directly, it diverges from the source, so you need an operational agreement — receive revision requests as comments and reflect them into the source instead, for example.

4.5 Wiki / Online Tools — a “Living Spec” Under Ongoing Maintenance

For a system under an ongoing maintenance contract with frequent modifications, keeping the spec continuously updated in an online tool such as Notion or Confluence is also a strong option. It offers good searchability, keeps change history automatically, and is a format that makes it easy to maintain a “living document” rather than one that’s simply “delivered and done.”

Viewed as a deliverable, though, you need to settle up front what’s left once the contract ends: the export format (can it be exported to Word or PDF), who owns the workspace and pays for it, and how viewing accounts are handled. Leave this vague, and you risk getting locked into a specific tool, losing access to the document the moment the contract ends.

5. How to Run the Back-and-Forth on Spec Changes

Even with a proper format in place, the “which is the latest version” problem recurs without an operational process, because specs keep changing — during development and just as much during the maintenance phase, not just up to delivery. Here’s the basic shape I’d recommend.

1. Keep a single change-management ledger: a list that records the change number, date, content, impact (cost/schedule), and who signed off on it, one row per entry. A plain Excel table is plenty for this on its own. Line it up with the change-management procedure in the IPA model contract (see the article mentioned earlier).
2. Send document revisions back and forth with the diff visible: for Word, turn on track changes before sending a revision, and let the client focus their review on the red marks. If you’re worried about a change slipping through untracked, the receiving side can catch it by running Word’s “Compare” feature against the previously agreed version. Once it’s agreed, accept the tracked changes and finalize that version.
3. Decide on a version-numbering rule: call the accepted version v1.0, and bump it to v1.1, v1.2, and so on with each agreed change. Never use “final,” “revised,” or “(2)” in a file name.
4. Freeze each agreed version as PDF, and have both sides keep a copy: make sure anyone can identify, after the fact, exactly which version was agreed on.

Whatever tools you use, keeping these four points running heads off almost all of the two big classes of trouble — “we don’t know what changed” and “we don’t know which is the agreed version.” Put the other way around, agreeing on the operational rules matters more than choosing the tool.

6. What the Client Should Check Before Signing the Contract

For the client’s side, here’s a checklist of what to confirm during the quoting and contracting stage.

• Does the deliverables list include the spec and design documents at the level of specific document names (as opposed to a vague “full set of documentation”)?
• Will you receive an editable original (a Word/Excel file, etc.)? Is it PDF-only?
• When you receive a revision, is it presented in a form that shows what changed (track changes, a list of changed sections)?
• Does the maintenance contract’s scope include updating the documents when a modification is made? If not, are you fine with the documents drifting out of date over time?
• How the document’s copyright and secondary use are handled — can it be handed over if you commission maintenance to a different company in the future?
• Is the procedure for spec changes decided (a change-management ledger, how agreement gets recorded)?

From the contractor’s side, this same list is directly useful for organizing an estimate. Which document to write, at what level of detail, is effort — and effort is money. Take on a project with the scope of deliverables left vague, and right around delivery you’ll hit a mismatch — “we assumed this document was obviously included too.” Agreeing on the list and format of documents up front protects both sides.

7. FAQ

Q1. The client specified an Excel graph-paper template. Do we just have to follow it?

Following the specified deliverable format is indeed part of the contractor’s job, but it’s worth confirming the purpose behind that requirement. If the goal is an internal documentation standard or audit compliance, there’s often room to propose meeting the same requirement in a Word format instead, and not infrequently the template is just something left over from old habit. Even when the specification can’t be changed, operational workarounds — attaching a “list of changed sections” to each revision, freezing agreed versions as PDF — can mitigate most of the problems caused by not being able to see the differences.

Q2. We only received the spec as a PDF. Is that a problem?

It doesn’t look like a problem at the time, since it’s readable — but it causes trouble once you reach the maintenance or modification stage. Editing a PDF isn’t impossible with specialized tools, but continuing to update it while preserving its structure the way you would with a Word or Excel original isn’t realistic, and the implementation drifts further from the document with every specification change. It also makes handover harder if you ever need to commission a different company for maintenance in the future, since there’s no editable original. The reliable approach is to spell out, at contract time, that “delivery includes an editable format” as a condition of the deliverables. If you’ve already received PDF-only, try asking the development company to provide the original.

Q3. How much detail should we ask for in the spec?

“The more detailed, the better” isn’t actually true. A more detailed document costs more to update and drifts from the implementation more easily. The benchmark is that behavior is specified precisely enough to serve as a basis for acceptance testing, and that the information referenced during maintenance and modification — screen fields, data structures, external integrations, business rules — is retained. A line-by-line account of implementation details that you could just as easily get by reading the code drifts less if it lives in the code and its comments rather than in a document. The level of detail translates directly into effort and price, so it’s something to align on before the contract is signed.

Q4. After delivery, whose responsibility is it to keep the spec updated?

It depends on the contract. If the maintenance contract’s scope includes “updating design documents when modifications are made,” it’s the contractor’s job; if it doesn’t, either document updates get commissioned separately with each modification, or the document is treated as something that will simply drift out of date. The situation that most easily turns into a dispute is when neither side settles this and both just assume “of course it’s being kept updated.” When you sign a maintenance contract, it’s worth spelling out, at the level of specific document names, exactly which documents are within the scope of maintenance.

Summary

Here’s a recap of this article’s key points about specs delivered in contracted development.

• Choose the format of a delivered spec based on acceptance testing, spec changes, and maintenance — not on “is it easy to write during development” alone.
• The core problems with Excel graph paper are acceptance testing becoming hollow and the loss of any record of agreement, both from an inability to see diffs, plus drift from the implementation driven by the high cost of updating it.
• The conclusion isn’t “abolish Excel entirely” — it’s returning to putting the right tool in the right place: prose in Word (styles + track changes), tables in genuine Excel tables, and a record of agreement frozen as PDF.
• Managing the development side’s source in Markdown + Git and generating Word/PDF as the deliverable is a setup that gets the benefits of both sides at once.
• Before format, settle the list of deliverables, delivery of an editable original, and how copyright is handled — in the contract. Agreeing on operational rules matters more than the tool.

On a related note, reading and writing Excel from a program (report generation) is covered in Building Excel Report Output - COM/Open XML/Templates, and structuring the contract itself is covered in the article explaining the IPA model transaction contract. Worth reading alongside this one.

For Anyone Considering Outsourced Development or Maintenance

At Komura Software LLC, when we take on contracted development of Windows business apps, we make it a practice to agree with the client up front on the scope, format, and update process for deliverable documents, using exactly the thinking introduced in this article. We also take on investigations for modifications to existing software starting from a state of “a spec exists, but we don’t know whether it matches reality.” Feel free to reach out, including for work on tidying up specifications or revisiting the delivery format.

Related Articles

Recent articles sharing the same tags. Deepen your understanding with closely related topics.

Related Topics

These topic pages place the article in a broader service and decision context.

Where This Topic Connects

This article connects naturally to the following service pages.

Frequently Asked Questions

Common questions about the topic of this article.

The client specified an Excel graph-paper template. Do we just have to follow it?

Following the specified deliverable format is indeed part of the contractor's job, but it's worth confirming the purpose behind that requirement. If the goal is an internal documentation standard or audit compliance, there's often room to propose meeting the same requirement in a Word format instead, and not infrequently the template is just something left over from old habit. Even when the specification can't be changed, operational workarounds — attaching a 'list of changed sections' to each revision, freezing agreed versions as PDF — can mitigate most of the problems caused by not being able to see the differences.

We only received the spec as a PDF. Is that a problem?

It doesn't look like a problem at the time, since it's readable — but it causes trouble once you reach the maintenance or modification stage. Editing a PDF isn't impossible with specialized tools, but continuing to update it while preserving its structure the way you would with a Word or Excel original isn't realistic, and the implementation drifts further from the document with every specification change. It also makes handover harder if you ever need to commission a different company for maintenance in the future, since there's no editable original to hand over. The reliable approach is to spell out, at contract time, that 'delivery includes an editable format (the Word or Excel original)' as a condition of the deliverables. If you've already received PDF-only, try asking the development company to provide the original.

How much detail should we ask for in the spec?

'The more detailed, the better' isn't actually true. A more detailed document costs more to update and drifts from the implementation more easily during the maintenance phase. The benchmark is that behavior is specified precisely enough to serve as a basis for acceptance testing, and that the information referenced during maintenance and modification — screen fields, data structures, external integrations, business rules — is retained. Conversely, a line-by-line account of implementation details that you could just as easily get by reading the code drifts less if it lives in the code and its comments rather than in a document. How much detail goes into which document translates directly into effort — that is, into the quoted price — so it's something to align on before the contract is signed.

After delivery, whose responsibility is it to keep the spec updated?

It depends on the contract. If the maintenance contract's scope includes 'updating design documents when modifications are made,' it's the contractor's job; if it doesn't, either document updates get commissioned separately with each modification, or the document is treated as something that will simply drift out of date. The situation that most easily turns into a dispute is when neither side settles this and both just assume 'of course it's being kept updated.' When you sign a maintenance contract, it's worth spelling out, at the level of specific document names, exactly which documents are within the scope of maintenance.

Author Profile

Profile page for the article author.

Go Komura

Representative of KomuraSoft LLC

Focused on Windows software development, technical consulting, and investigations into failures that are difficult to reproduce.