A website redesign completes, and deliverables are handed over, including an 80-page "operations manual." Six months later, an employee needing to post a news item opens the PDF, scrolls for a few minutes, closes it, and emails the agency: "Could you please post this news update for us?"
Documentation is not absent; in fact, an impressive manual was provided. Yet it goes unused. This outcome reflects an architectural flaw in documentation design, rather than laziness by readers or cutting corners by writers.
Four distinct types mixed into a single book
In technical documentation design, there is a framework known as Diátaxis. Its core principle is separating documentation into four distinct types without mixing them: tutorials, how-to guides, reference, and explanation.
Their respective roles are divided as follows:
| Type | Who reads it, and when | Description |
|---|---|---|
| Tutorials | First-time users, to learn | An experience guaranteed to succeed if followed step by step |
| How-to guides | Active workers, to accomplish a specific goal | Goal-oriented steps, such as "posting a news update" |
| Reference | Users needing verification, for precision | Catalog of parameters, field names, and technical specifications |
| Description | Decision-makers, for contextual understanding | Background explaining why choices were made |
The 80-page manual mentioned earlier mixes these four types in no particular order. Initial setup tutorials are wedged between exhaustive field-by-field reference lists of CMS screens, followed immediately by architectural explanations.
A team member who simply wants to publish a news update needs only a single-page how-to guide. Because they cannot tell where that page is hidden in an 80-page manual, calling the agency is faster than searching. That is the entire reason documentation is abandoned.
Delivering the four types separately changes everything. If common tasks are gathered in a slender, dedicated booklet, employees will readily open it. Exhaustive lists of every parameter are needed only during troubleshooting, never in routine work.
Procurement should specify workflows, not page counts
When an estimate simply lists "Operations Manual," discussions typically devolve into volume: how many pages, or how many screenshots. Defining these metrics will not change whether the manual gets used.
What should be specified is identifying daily operational tasks by name and demanding standalone how-to guides for each. For a corporate website, examples include:
- Publishing a news or blog article
- Updating text and images on existing pages
- Changing the destination email address for contact forms
- Adding a new team member to the staff profile page
Only the client can compile this list, because the agency does not know what your team updates most frequently. Provided with this list, however, the agency can produce targeted how-to guides for each task.
During acceptance testing, make it a condition that internal staff actually perform each task once while following the guide. Feeling you understand something by reading is completely different from carrying it out. Any point where staff get stuck highlights a gap in the manual. Adding this test visibly transforms documentation quality.
Reference and explanation serve different moments
While how-to guides cover day-to-day operations, the remaining two types are indispensable in specific circumstances.
Reference documentation proves its worth during personnel handovers and agency transitions. Lists of settings, third-party services and their roles, and domain or account credentials are rarely checked in daily work, but handovers stall without them. Deciding to switch agencies only to abandon the transition due to missing configuration sheets is a common pitfall, explored in What happens when you lose contact with your development vendor.
Explanation proves its worth whenever modifications are planned. Without written rationale explaining why a feature was built a certain way, future developers must re-evaluate all past decisions from scratch. Years later during redesigns, having original design intent documented dramatically cuts discovery time.
In short, the four types are read at entirely different times: how-tos monthly from day one, reference during handovers, and explanation years later. Bundling them into one volume ignores this timeline.
"Having documentation" and "keeping it updated" are two different things
Another prerequisite to define during procurement is who is responsible for updating the documentation.
Websites evolve after launch: pages expand, features are added, and external integrations change. Procedures become obsolete with every change. If an interface no longer matches screenshots six months later, the manual is promptly discarded.
When entering a maintenance agreement, ensure the scope explicitly includes updating relevant documentation whenever system revisions occur. If this is left vague, updates become nobody's job. If not included in the contract, the client must take ownership of maintaining it. Either choice is acceptable, but leaving it undefined yields the worst outcome.
The consequences of leaving a website unmaintained are outlined in The risks of neglecting your website, while cost structures are detailed in Maintenance costs for business systems.
Prepare a single sheet for your next procurement
If you are planning to commission website or software development, draft a single A4 page before requesting estimates.
Compile a bulleted list of operations your staff want to perform independently post-launch. Ten lines are plenty; in most organizations, routine tasks easily fit within that scope.
Attaching this list to your RFP achieves two things: relevant procedural guides will be included in deliverables, and whether the administration UI actually enables staff self-sufficiency will be evaluated during initial architecture design. If your requirement to self-publish news updates is shared upfront, the admin console will be engineered to support it.
While framed as a documentation discussion, this is fundamentally about whether your organization can operate independently after launch. That makes clarifying it before procurement well worth the effort.
Whether planning a website overhaul designed for internal maintainability or reviewing whether existing handover documentation is truly viable, GleamHub offers free website and redesign consultations. Optimal architecture varies by requirement, so we provide individualized quotes. Please contact us via our inquiry form.
