Member portal: the specification outline to reuse
A specification is not a design document, it is a decision document: it exists so two quotes can be compared. Here is the outline that works, section by section, and what to keep out of it.
Most specifications for a member portal fail the same way. They are eighty pages long, written alone over three weekends, exhaustive on the screens and silent on the data. Three suppliers read them and quote three different projects. The document has done the opposite of its job — because its job was never to describe the software.
What a specification is actually for
It exists to make two quotes comparable. That is the whole point. Everything that helps a supplier price the same scope as its competitor belongs in it; everything that describes how the supplier should build belongs to the supplier. Judged by that criterion, twenty tight pages beat eighty exhaustive ones every time.
A second, less obvious purpose: writing it forces your organisation to answer questions it has been avoiding. Who is allowed to see another member's revenue figures? What happens to a member who leaves mid-year? Those answers are worth more than the document itself, and they are the reason a specification should never be written by one person alone.
The outline, section by section
Context and objectives
Who you are, how many member companies and suppliers, what runs the process today and what breaks. Then three to five objectives, each with a way of knowing it was met. Not slogans: reduce the declaration campaign from six weeks to two, stop retyping figures, give members access to their own history.
Functional scope, by actor
One section per actor, describing what they come to do. This is the heart of the document, and the section developed further below.
Roles and permissions
A grid: for each role, what it can read, create, modify, validate. Name the sensitive cases explicitly — a member must never see another member's declarations, a supplier sees only its own agreements, the permanent team sees everything but signs nothing.
Critical journeys
Three to six end-to-end sequences described in plain sentences: declaring quarterly revenue, submitting an approval application, finding last year's agreement, running the annual close. Include the failure paths — the late declaration, the rejected file, the disputed figure.
Data and migration
What exists, where, in what state, and what must be carried over. Number of members, suppliers, agreements, documents, years of history. Say honestly what is dirty: duplicates, companies renamed, documents with no metadata. This is the section suppliers use to tell whether you have looked.
Non-functional requirements
Availability, volumes, personal data, hosting, backup, browsers, languages. Detailed below, because this is where buying groups have genuinely specific needs.
Reversibility and ownership
Who owns the source code, what is handed over and when, in what form the data can be exported, what happens if the relationship ends. Write it as a requirement, not as a hope expressed during the negotiation.
Acceptance arrangements
Who tests, on which data, against which list, and what a failed test triggers. State that acceptance runs on real data, not on samples, and that final acceptance requires one complete cycle in production conditions.
Schedule and milestones
Your immovable dates — declaration windows, the annual close, the general meeting — and the batches you want delivered around them. Give constraints, not a Gantt chart: the sequencing is part of what you are buying.
Selection criteria
Announce how you will decide, with weightings. A supplier who knows that business understanding counts for 40 % and price for 25 % writes a different, more useful proposal.
Describe the scope by actor, not by screen
The most common mistake is to list features: a news area, a document area, a form. A feature list cannot be challenged, because nothing in it says what it is for. A description by actor can: it states who does what, and any supplier worth hiring will come back with questions about the edges.
| Actor | What they come to do | What the specification must state |
|---|---|---|
| Member | Declare revenue, track their rebates, find agreements, update their company details | Which figures they may see about themselves, what they may see about the group, who validates their changes |
| Supplier | Consult their agreement, follow the volumes attributed to them, submit documents | Whether they see member-level detail or aggregates only — the answer is rarely obvious and always contentious |
| Permanent team | Chase, check, validate, run campaigns, answer disputes | Which actions require a second pair of eyes, and what they can correct on a member's behalf |
| Administrator | Manage accounts and permissions, open and close campaigns, maintain reference data | Who holds this role, how many people, and what is traced when they act |
| Membership applicant | Submit an application and follow its progress before having an account | What a non-member can access, and how an application becomes a member record without retyping |
The non-functional requirements that actually matter here
Generic specifications copy a paragraph about performance and move on. For a buying group, four points deserve real sentences.
- Availability during declaration windows. Traffic is not spread across the year: forty of your sixty members declare in the last forty-eight hours before the deadline. Say so, and say what an outage during those two days would cost — that is what sizes the hosting.
- Volumes, in figures. Number of accounts, declaration lines per campaign, documents stored and their average size, years of history kept online. A supplier who receives no figures will assume the smallest ones.
- Personal data. Your members' contacts are personal data: retention periods, who may export a list, subcontractor obligations, the processing register. Ask for a data processing agreement in the response, not after signature.
- Hosting and recovery. Where the data physically sits, backup frequency, how much data you accept to lose in an incident and how long you accept to be down. Two numbers, and they are yours to set, not the supplier's.
What to keep out of it
Three things ruin an otherwise good specification, and all three come from a genuine desire to be helpful.
Imposed technical solutions, first. Naming the database, the framework or the architecture before anyone has understood the process eliminates suppliers for the wrong reasons and removes your only lever if the choice turns out badly. Describe constraints instead — an existing single sign-on, an accounting export format, a hosting requirement — and let the responses argue for the rest.
Screens drawn in advance, second. Detailed mock-ups feel like precision; they are the fastest way to freeze a solution before the problem is understood. They also transfer responsibility: a supplier who builds your screens exactly as drawn cannot be held to account for their usability. A sketch to illustrate an intention is fine. A screen-by-screen specification is a design decision you are making without the information to make it.
False exhaustiveness, third. Three hundred numbered requirements, most copied from a package's feature list, produce a document nobody reads to the end and a scope nobody can price. Worse, they hide the fifteen requirements that genuinely matter. And the last omission, the one that costs the most time: refusing to state a budget envelope. Withholding it does not get you a better price, it gets you three quotes aimed at three different projects.
The questions to settle before writing a line
- Which single process, if it improved, would justify the project on its own?
- Who, by name, is entitled to arbitrate a functional disagreement — and are they available every week?
- What can a member see about other members? The answer is a governance decision, not a technical one.
- What are our immovable dates, and how many months of margin do we actually have?
- What do we do with fifteen years of history: migrate it, archive it, or leave it where it is?
- Which tools must the portal talk to, and who controls each of them?
- What happens on the day a member disputes a figure — who answers, with what evidence?
- What is our envelope, and what would we give up first if the quotes came in above it?
Comparing the responses
Score business understanding first: not the promises, but the questions asked. A supplier who comes back asking whether your growth bonus is measured at constant perimeter has read the document; one who returns a price by email has not. Then require a price per batch rather than a single figure, ask who will actually do the work — names, not a capability statement — and ask for one comparable reference by size and by process, not by industry sector.
A specification is not a design document, it is a decision document. It has to be precise enough that two quotes can be compared, and open enough that a supplier who knows the domain can contribute something you had not thought of. That balance is easier to hold than it sounds: it comes from writing the document with the two or three people who actually run the process, rather than about them. Twenty pages written that way will get you further than eighty written alone — and you will already know, before the first quote arrives, which parts of your own process nobody can explain.
Continue reading
What rebuilding a buying group's system really costs
Nobody publishes figures for this kind of project, which leaves general managers walking into board meetings empty-handed. Here are defensible ranges, batch by batch, and the three cost items no quote ever contains.
Rebates and year-end bonuses: what software must compute
The accounting difference between a rebate and a year-end bonus takes two paragraphs. The mechanics your software has to model — tiers, bases, pro-rata, versioned scales — take a project.