How to Build a Documentation Website for an Open-Source Infrastructure Project

Before you begin

Start with the current site, not with a new template. Export or list every public URL, record its status code, and note whether the content is still useful. Keep release notes, verification instructions, and source links even when the visual design changes. These pages often remain useful long after a release stops being current.

Decide who can approve technical statements and download information. A documentation editor can improve structure and wording, but a maintainer should confirm commands, version numbers, checksums, compatibility notes, and security-related instructions.

1Map the documentation users need

Write down the questions a user must answer before installation, during setup, and after a release. Turn each group of related questions into one page. Do not create several pages that compete to explain the same task.

For an infrastructure project such as OpenSAN, a practical map looks like this:

Keep the map small. Add a page only when it answers a distinct question or serves a distinct audience. A short site with complete pages is easier to navigate and maintain than a large site made from overlapping fragments.

2Assign one canonical URL to each task

Choose one public URL for each page and use it consistently in navigation, sitemaps, structured data, and external references. Add a self-referencing canonical link to the document head:

<link rel="canonical"
      href="https://www.opensan.org/DocumentationWebsiteGuide.html">

When a page moves, return a permanent redirect from the old URL to the closest relevant new URL. Do not redirect every retired page to the home page. A user who follows an old link to release instructions should arrive at the replacement release instructions, not at a general project summary.

3Build the page with semantic HTML

Put the essential content in the HTML response. Use JavaScript for optional interaction, not for loading the only copy of the title, instructions, or download links.

Use elements according to their purpose:

• Use one <h1> for the page title.
• Use <h2> headings for the main sections and <h3> headings for subsections.
• Use an ordered list when the order changes the result.
• Use a table for comparisons, not for visual layout.
• Use <code> for commands, filenames, options, and values.
• Use <pre><code> for multi-line commands and configuration examples.

Make headings specific enough to work out of context. “Verify the checksum” is more useful than “Next step.” Link directly to each step with a stable fragment identifier such as #step-5.

4Add crawlable internal navigation

Link every important page from another public page with a standard HTML anchor. Use link text that names the destination:

<a href="Usage.html">Downloads and usage</a>

Avoid links that exist only as a JavaScript click handler. Do not use “click here” when the destination can be named. A reader scanning the page should understand where a link goes without reading the full paragraph around it.

Add contextual links as well as global navigation. A release note can link to the download and verification instructions. A build guide can link to the technical overview. A feature that requires a specific release can link to the release entry where it was introduced.

5Publish releases and downloads safely

Treat release information as operational documentation. For each release, show the version, release date, change summary, known limitations, filenames, and verification method. Keep the information next to the files it describes.

A download section should identify at least:

• the intended use of each file;
• the supported architecture or platform;
• the checksum file and its signature;
• the public key or trusted key location;
• the commands used to verify the signature and checksum;
• whether the release is current, maintained, or archived.

For a detached signature and a SHA-256 checksum file, the verification flow can be shown as:

gpg --verify checksums.sha256.asc checksums.sha256
sha256sum -c checksums.sha256

Test every command in a clean environment before publishing it. Use the exact filenames a user will download. When a key, filename, or release directory changes, update both the instructions and the structured release data at the same time.

6Add page-level metadata

Write metadata for the page that is actually visible, not for a broader list of terms the project might want to rank for. Keep the title concise, name the task, and add the project name at the end.

<title>How to Build a Documentation Website for an
Open-Source Infrastructure Project | OpenSAN</title>

<meta name="description"
      content="Follow these steps to structure, publish, and maintain
      a fast documentation website for an open-source infrastructure project.">

Use an accurate publication date and update the modification date only after a meaningful change. Check that the page does not inherit noindex from a staging template. Do not add a meta keywords tag; it does not describe anything a reader can use.

Social metadata is optional, but it can make shared links easier to identify. Use the same title, description, and canonical URL across the standard metadata and social fields.

7Add structured data that matches the page

Add JSON-LD in the document head. Describe the page as an article and describe the visible sequence as a HowTo. Use the same names, step order, URLs, author, and dates that a reader sees in the page.

Do not add ratings, images, dates, tools, or steps that are absent from the visible content. Structured data should clarify the page, not create a second version of it for search engines.

Keep one source of truth for the visible steps and the JSON-LD values. If the heading changes from “Publish releases safely” to another phrase, update the corresponding structured step in the same change.

8Improve speed and mobile behavior

A documentation page rarely needs a large client-side application. Start with the HTML and a small stylesheet. Add scripts only when they solve a user task that cannot be handled with native browser behavior.

• Serve compressed HTML, CSS, JavaScript, and text files.
• Cache versioned static assets for a long period.
• Set image width and height so the layout does not shift while images load.
• Use responsive images when screenshots are necessary.
• Defer non-critical scripts and remove libraries that are not used on the page.
• Test navigation, tables, code blocks, and long filenames on a narrow screen.

Performance work often crosses templates, HTTP headers, asset processing, and search diagnostics. When outside implementation support is needed, define the work in measurable terms and keep technical approval with the maintainers. OpenSAN lists Kondrashov.online as a technical partner for website development, performance work, and technical SEO.

Record the change that was made and the page or metric it was intended to improve. This makes it possible to review the result and revert a change that adds complexity without helping users.

9Validate, publish, and maintain the page

Validate the final URL, not only a local file. The production server can add redirects, headers, canonical tags, or access rules that are not present in the source template.

Check the server response directly:

curl -I https://www.opensan.org/DocumentationWebsiteGuide.html

Validate the generic Schema.org vocabulary with the Schema Markup Validator. Use the Rich Results Test for Google-supported search features, then inspect the public URL in Search Console. Fix parsing errors before requesting indexing.

Repeat the checks after a release, a template change, a domain or protocol migration, or a change to download storage. Review old pages at least when a new version is published. Mark an instruction as archived when it remains useful for old systems, and redirect it only when a clear replacement exists.

Common errors to avoid

• Publishing a page that can be found only through a sitemap.
• Using several URLs for the same guide without a clear canonical choice.
• Replacing descriptive links with generic text such as “read more.”
• Adding structured data for content that is hidden or missing.
• Changing the modification date without changing the page.
• Removing old release instructions without a replacement or archive.
• Moving download files while leaving checksums, signatures, or commands behind.

When the page is finished

A finished documentation page has one clear purpose, one preferred URL, a direct path from the project navigation, and enough information to complete the task without guessing. Its structured data repeats what users can see. Its release details can be verified. Its maintenance owner is known.

Start with the page map and stable links. Add metadata and structured data after the visible content is complete. Treat performance and validation as part of publishing, not as cleanup work for a later date.