Installation Guide

Agent Prompt Snippet

Ensure the project has an installation guide covering all supported platforms, installation methods, first-run configuration, and verification of a successful install.

Purpose

An installation guide is the document that takes a user from zero to running for the first time. It covers supported platforms, the available installation methods, any prerequisites, the installation commands themselves, first-run configuration, and how to verify that the installation succeeded.

The installation guide is high-stakes documentation. A developer’s first impression of a project is formed during installation. Friction, confusing instructions, or a failed install is enough to cause many users to abandon the project entirely—even if the software itself is excellent. Conversely, an installation that goes smoothly in under two minutes creates positive momentum that carries through the entire user journey.

The installation guide is also the highest-priority documentation to keep accurate. Configuration specs and API docs can lag slightly behind the implementation without causing immediate user failures. Installation instructions that are wrong stop users before they get started.

For CLI tools, the installation guide is the entry point for three distinct audiences: users installing via package manager (Homebrew, apt, scoop), users downloading a pre-built binary, and developers building from source. All three paths must work and all three must be documented.

Who needs this document

Persona	Why they need it	How they use it
Sam (Indie Dev)	First contact with the tool; a smooth install is prerequisite to everything else	Follows installation guide; expected to reach first successful run in under 5 minutes
Claude Code (AI Agent)	May need to verify or recreate a development environment; installation guide is the ground truth	Reads installation guide when asked to set up a development environment or debug installation issues
Leo (OSS Maintainer)	Contributors must build from source; new contributors follow the installation guide	Runs through the installation guide on every release to verify accuracy
DevOps (CI Operator)	CI environments must install the tool reliably; uses installation guide to write CI setup scripts	Adapts installation steps into CI workflow YAML; verifies on Linux/macOS/Windows per supported platforms

What separates a good version from a bad one

Criterion 1: Platform coverage is complete and each path is separately tested

✓ Strong: “Supported platforms: macOS 13+ (Apple Silicon and Intel), Linux amd64/arm64 (glibc 2.31+), Windows 10+ (x64). Each platform has its own installation section. CI matrix tests the install command on each supported platform and Go version. Unsupported platforms: FreeBSD (no binary; build from source works), Windows arm64 (coming in v1.1).”

✗ Weak: “Works on macOS, Linux, and Windows.” (No version requirements, no architecture specifics, no list of what doesn’t work. Users on Windows 7 or Alpine Linux discover incompatibility the hard way.)

Criterion 2: Installation reaches a verifiable running state

✓ Strong: “After installation, run specbase version — you should see:
specbase v1.2.0 (linux/amd64, built 2026-03-15)
If this command produces output, the installation succeeded. If you see command not found, the binary is not in your PATH — see Troubleshooting below.”

✗ Weak: “Follow the steps above to install the tool.” (No verification step. The user has no way to confirm success other than trying to use the tool and encountering whatever error occurs first.)

Criterion 3: Common failures and fixes are documented

✓ Strong: “Troubleshooting: (1) command not found after Homebrew install: run brew shellenv and add the output to your shell profile. (2) Permission denied on /usr/local/bin: use --prefix ~/.local with Homebrew or place binary in ~/bin. (3) GLIBC version error on Linux: your distribution uses musl libc (Alpine) — download the static binary instead of the glibc binary. (4) Certificate errors during download: use --no-check-certificate only in air-gapped environments.”

✗ Weak: “Contact support if you encounter issues.” (Users will not contact support for an open-source tool. They will abandon it. Document the top-5 failure modes you see in GitHub issues.)

Criterion 4: Build-from-source instructions are complete

✓ Strong:
# Prerequisites: Go 1.23+
git clone https://github.com/aallbrig/specbase
cd specbase
make build
# Binary at ./bin/specbase
./bin/specbase version
“Build requires Go 1.23 or later. To install Go, see go.dev/dl/. The build takes approximately 30 seconds on a modern machine.”

✗ Weak: “Build from source by running go build.” (Which directory? Which package? Where does the binary end up? What version of Go is required?)

Common mistakes

Documenting the golden path only, not the degraded path. Installation guides written by developers who have the tool already installed often miss the prerequisite installation steps that are obvious to them but opaque to users. Write the guide by following it on a clean machine from scratch.

Not documenting package manager caveats. Each package manager has quirks: Homebrew on Apple Silicon may require Rosetta; apt-get on Ubuntu 20.04 may have a different package name than Ubuntu 22.04; Scoop on Windows requires Set-ExecutionPolicy RemoteSigned. Document these before users hit them.

Installation guide that diverges from CI. The CI pipeline installs the tool in a specific way; if the installation guide documents a different way, one of them is wrong. Keep them in sync. Ideally, the CI install command is exactly the command shown in the installation guide.

No uninstall instructions. Users who need to switch to a different version, debug a corrupt install, or just clean up their system need to know how to uninstall. A 3-line uninstall section prevents support burden.

How to use this document

When to create it

Write the installation guide before the first public release. Update it with every release that changes the installation process. Run through the full guide on a fresh environment before each major release to catch documentation drift.

Who owns it

The engineering or developer relations team. For open-source projects, the core maintainer owns accuracy; the community contributes platform-specific tips via pull requests.

How AI agents should reference it

get_standard_docs(type="cli_tool", features=[])
→ install_guide in documents[]
→ agent reads install guide before writing CI setup scripts or helping users debug installation
→ agent uses documented commands for each platform rather than guessing
→ agent follows troubleshooting section before escalating installation issues

The prompt_snippet — “Ensure the project has an installation guide covering all supported platforms, installation methods, first-run configuration, and verification of a successful install” — tells the agent to verify all four dimensions are covered.

How it connects to other documents

The Installation Guide feeds from the Configuration Specification (first-run configuration) and the README (which links to the installation guide). The Packaging Guide documents how release artifacts are built and distributed—the two documents are complementary.