How to Plan and Build a Documentation Website for Any Software Project

Start with five deliverables

A documentation project becomes manageable when every phase ends with something concrete. Before writing new pages, create these five small artifacts. They can live in a spreadsheet, repository, or issue tracker; the format matters less than keeping them together and current.

For a small project, one person may produce all five. For a larger product, assign a documentation editor to structure and wording, engineering owners to technical accuracy, and a release owner to versioned material. Do not make the editor guess whether a command is safe or still supported.

1Define users, outcomes, and owners

Deliverable: a short audience-and-task list.

Begin with tasks, not with a navigation menu. “Developer” and “administrator” are useful labels, but they do not tell you what the documentation must help them do. Write one sentence for each real outcome: evaluate the product, install a supported version, connect an application, upgrade without losing data, diagnose a failure, or remove the product cleanly.

For each outcome, record:

• who is doing the work and what they already know;
• the environment, platform, or product version involved;
• what must be true when the task is complete;
• what can go wrong or cause irreversible damage;
• who can verify the instructions and approve future changes.

Prioritize tasks by consequence and frequency. Installation, security, upgrades, backups, data migration, and recovery normally deserve verified pages before background material or minor customization. A rarely used recovery guide may still be critical because the cost of getting it wrong is high.

2Inventory existing content and URLs

Deliverable: one row for every public page, file, and known legacy URL.

If a site already exists, do not begin by replacing its template. First collect what users and external sites can reach: HTML pages, PDFs, release notes, package files, API references, old wiki paths, translated pages, and URLs found in analytics, server logs, sitemaps, repositories, issue discussions, or backlink reports.

A practical inventory uses these columns:

url,title,type,status,owner,last_verified,inbound_links,action,destination
/setup/,Install the server,task,200,platform,2026-07-01,yes,keep,
/old-install.html,Legacy install,task,200,platform,unknown,yes,redirect,/setup/
/v1.pdf,Version 1 manual,archive,200,release,2024-03-10,yes,archive,

Give every item one action:

3Design a task-based page map

Deliverable: one page purpose and one preferred URL for every documented task.

Organize the site around the questions users bring to it. Product teams often mirror their own departments or code modules in the menu, but those boundaries may be invisible to a new user. A useful top level usually combines a small number of durable groups:

• Overview: what the product does, where it fits, and its limits;
• Get started: prerequisites, installation, first successful result;
• Guides: complete tasks and operational workflows;
• Reference: commands, configuration, API fields, and exact values;
• Operations: upgrades, backup, monitoring, security, and recovery;
• Releases: changes, compatibility, downloads, and verification;
• Support: troubleshooting, known issues, and contact routes.

This is a starting point, not a required menu. A library may need API reference and examples but no operations section. A hosted service may need account administration and billing. Remove a section when it has no real content; empty categories make a site feel unfinished.

A worked OpenSAN page map

OpenSAN is an infrastructure project, so its compact map emphasizes capabilities, architecture, releases, and usage. The same columns can be reused for another project while the rows change.

Before accepting the map, walk through three complete journeys: a first evaluation, a first successful setup, and a failed setup. If a user must search the web or guess the next page, the path is incomplete.

4Choose a publishing method

Deliverable: a short decision record naming the platform and why it fits.

Choose the simplest method that supports the real editing workflow. The page map and content model should survive a future platform change; do not let a theme or plugin decide the structure of the documentation.

Also decide how previews are created, who can publish, where source files live, how changes are reviewed, and how a previous release is restored. A platform is not complete until an editor can see a draft and a maintainer can roll back a bad publication.

5Build reusable page templates

Deliverable: templates for tasks, concepts, reference, troubleshooting, and releases.

Do not force every kind of information into one article layout. A task guide tells a reader what to do in order. A reference page helps them look up an exact value. A concept page explains why the system behaves as it does. A troubleshooting page starts with a symptom. Templates make these differences visible and reduce omissions during writing.

# [Action and object]

Use this guide to [observable outcome].

## Before you begin
- Supported versions:
- Required access:
- Required tools or files:
- Backup or safety warning:

## Steps
1. [Action]
   Expected result: [what the user should see]
2. [Action]
   Expected result: [what the user should see]

## Verify the result
[Command, request, screen, or behavior that proves success]

## Undo or recover
[How to return to a safe state]

## Troubleshooting
[Symptom] - [diagnostic action] - [fix]

## Next steps
[One or two relevant links]

Keep shared elements shared: site navigation, breadcrumbs, product and version labels, page owner, last verified date, feedback route, and footer. A template should remove repetitive decisions, not fill pages with boilerplate that says nothing about the task.

6Write instructions that can be followed

Deliverable: a tested draft for each priority task.

Write while performing the task in a clean or representative environment. Record commands and results as they occur. Memory tends to omit prerequisites, inherited configuration, permissions, and decisions that experienced maintainers make automatically.

Each instruction should answer four questions:

1. What should I do? Begin with a concrete verb and name the object.
2. Where should I do it? Name the host, directory, interface, account, or configuration file.
3. What should happen? Show a meaningful success signal, not only “the command completes.”
4. What if it does not? Link the likely symptom to a diagnosis or safe recovery action.

Separate commands from output, and never put placeholders into a command without marking them. Explain whether a value must be replaced and give it a recognizable form such as <server-address>. State whether an action requires elevated privileges, restarts a service, changes data, or causes downtime.

Ask a person who did not write the page to follow it. Note every pause, assumption, wrong turn, and unexplained term. That short observation is usually more valuable than another round of stylistic editing.

7Connect pages with useful navigation

Deliverable: every important page is reachable through a meaningful user path.

Global navigation should expose the durable sections of the site. Contextual links should carry the reader through the current task: from prerequisites to installation, from a release note to upgrade instructions, or from an error to a diagnostic page.

Use ordinary HTML links with destination names that make sense on their own:

<a href="/guides/verify-download/">Verify the downloaded release</a>

Avoid generic labels such as “click here” and links that exist only in a JavaScript event handler. Add a section index when a group becomes too large for the main menu. Add breadcrumbs when users often enter on deep pages. At the end of a task, offer the next likely action rather than a long automatically generated list.

A sitemap is useful for discovery and diagnostics, but it is not a substitute for navigation. If an important page can be found only in the sitemap, the user journey and the internal link structure are both incomplete.

8Migrate URLs without losing useful paths

Deliverable: a one-to-one redirect map and a post-launch status report.

Keep an established URL when the page still serves the same purpose. When content moves, map the old address to the closest current replacement. Use a permanent server-side redirect for a permanent move. Do not send every retired page to the home page; that hides whether a real replacement exists and gives the visitor no answer to the original question.

Update internal links to point directly to the new URL. Include only preferred, indexable URLs in the sitemap. Keep protocol, hostname, trailing-slash, and letter-case rules consistent so one page does not appear under several addresses.

After launch, check both the first and final response:

curl -I http://example.org/install.html
curl -IL http://example.org/install.html

The first command should show the intended redirect. The second should end at the correct HTTPS page without a loop or a chain of avoidable intermediate redirects.

9Add technical publishing details

Deliverable: a complete page head, valid response, accessible layout, and current sitemap.

Technical details support the content; they cannot replace it. Finish the visible page first, then describe that exact page in metadata and structured data.

Use a complete, accurate page head

<title>Install Example Server on Linux | Example Project</title>
<meta name="description"
      content="Install Example Server, start the service, and verify
      the health endpoint on a supported Linux host.">
<link rel="canonical" href="https://docs.example.org/get-started/install/">
<meta name="robots" content="index,follow">

• Use a unique title and description that match the visible task.
• Set one self-referencing canonical URL on the preferred page.
• Use accurate publication and modification dates; do not change them automatically without a content change.
• Set the document language and use one clear main heading with logical subheadings.
• Keep essential text and links in the HTML response.

Use structured data only when it matches

An article can be described with TechArticle or Article. A visible, ordered procedure can also be described with HowTo. Use the same title, author, dates, step names, and order that appear on the page. Do not invent ratings, images, tools, or steps for the markup.

Schema.org still defines HowTo, but Google does not currently provide a dedicated How-to rich result. Treat structured data as a clear machine-readable description, not as a guarantee of a special search display.

Make the page robust

• Use semantic HTML for headings, navigation, main content, lists, tables, and code.
• Make keyboard focus visible and ensure links can be understood without color alone.
• Allow tables and code blocks to scroll on narrow screens instead of breaking the layout.
• Set image dimensions and write useful alternative text for informative images.
• Compress text assets, cache versioned files, and remove scripts the page does not use.
• Generate the sitemap from canonical public URLs when the site changes frequently.

10Test, publish, and maintain

Deliverable: a signed-off release and an update routine tied to product changes.

Test the production URL, not only a local preview. The server can introduce redirects, caching, authentication, content types, or indexing rules that do not appear in the source files.

Use change triggers, not arbitrary dates alone

A quarterly review can catch neglect, but documentation should change when the product changes. Add a documentation check to release work, configuration changes, API changes, security fixes, deprecations, support-policy changes, and domain or hosting migrations.

Measure whether users complete tasks, not only whether pages receive visits. Useful signals include failed internal searches, repeated support questions, exits during a procedure, broken-link reports, copied commands that fail, and pages that have not been verified for the current release.

A reusable project starter kit

Keep the planning files beside the documentation source. This small structure works with plain HTML, a static-site generator, or a CMS export process:

documentation/
  README.md                # audience, scope, publishing process
  content-inventory.csv    # every current and legacy URL
  redirects.csv            # old URL to new URL mapping
  owners.csv               # technical area and approver
  templates/
    task.md
    concept.md
    reference.md
    troubleshooting.md
    release.md
  checks/
    pre-publication.md
    release-review.md

In README.md, record how to preview the site, how to publish it, how to roll back, and where to report a documentation problem. A new contributor should not need private knowledge to make a small, safe correction.

Signs that the site needs another pass

• The navigation describes the organization chart or repository instead of user tasks.
• Several pages explain the same action but disagree about versions or commands.
• A procedure ends without a way to verify success.
• Search results lead to an old page that has no version label or replacement link.
• Every removed URL redirects to the home page.
• Release files are separated from their checksums, signatures, or compatibility notes.
• The page has polished metadata but thin, generic, or untested visible content.
• No person knows who must update the page after a product change.

Fix the earliest broken part of the workflow. More metadata will not repair an unclear page map, and a visual redesign will not repair instructions that no one has tested.

Official references

These references cover the technical standards used in this plan. They are useful during implementation, but the project's own tested behavior remains the source of truth for commands, compatibility, and operational warnings.

• Google Search Central: crawling and indexing
• Google Search Central: redirects and Google Search
• Google Search Central: canonical URLs
• Google Search Central: build and submit a sitemap
• MDN: semantic HTML
• Schema.org: TechArticle and HowTo

The useful result

A useful documentation site does not need to be large. It needs to connect a real audience to a verified result, preserve the addresses people already rely on, and make future changes routine. Start with users and tasks, turn them into a page map, write with reusable templates, and test the production path from beginning to end.

The five planning artifacts at the beginning of this guide can be reused for the next project. Replace the audiences, tasks, page rows, and technical owners; keep the workflow. That is what turns a one-off documentation site into a repeatable practice.