Topic 40

Documentation

Collaboration

GitHub gives you three documentation surfaces — the README rendered on the repo home, a version-controlled Wiki, and full sites published with GitHub Pages — each suited to a different audience and a different update cadence. Choosing the wrong surface for a kind of content is how docs end up either invisible or quietly wrong.

The single distinction that drives most of these choices is whether the docs must stay in lockstep with the code. Anything that describes the code should be reviewed in the same pull request as the code; anything that is reference, marketing, or collaborative notes can live in a surface that updates on its own schedule.

README and the Profile

The README is rendered on the repository home page and is the one-screen entry point: what this is, and how to get started. It supports relative links to other files in the repo, which is what keeps those links working across forks and renames. A repository named identically to your username hosts a special profile README shown on your GitHub profile.

Wikis

A Wiki is a separate Git repository attached to the project, convenient for long-form, collaborative notes. Its weakness is precisely that separation: because Wiki edits do not go through the main repo's pull requests, the Wiki drifts out of sync with the code it describes and no review catches the drift.

GitHub Pages

Pages publishes a website from a branch or a /docs folder, building static files or running Jekyll, and supports custom domains. When there is a build step, the modern path is to deploy Pages from an Actions workflow rather than directly from a branch, which keeps built output out of your source branches. A custom domain is not secure until "Enforce HTTPS" is checked.

Docs-as-Code in the Repo

For documentation that must track the code, keep Markdown in a /docs folder so it is reviewed in the same pull request as the change it describes. This is the docs-as-code approach, and it is the answer to Wiki drift: the docs cannot fall behind because they change in the same commit as the code.

Special Files

GitHub surfaces certain files in its UI when present, conventionally under .github/. A typical set looks like this:

.github/
  CONTRIBUTING.md       <- linked from the new-issue and new-PR forms
  CODE_OF_CONDUCT.md    <- surfaced on the community profile
  SECURITY.md           <- adds a "Report a vulnerability" path
  ISSUE_TEMPLATE/       <- templates offered when opening an issue
  PULL_REQUEST_TEMPLATE.md

Among these, SECURITY.md matters most for risk: without it, vulnerability reports land in public issues instead of a private disclosure channel.

README vs Wiki vs Pages

README — the one-screen entry point rendered on the repo home; use it for what-this-is and a quickstart. Wiki — a separate repo for collaborative long-form notes, convenient but prone to drift because it is not reviewed with the code.

Pages — a published website for polished docs or marketing, the choice when you need search, navigation, and a custom domain. For docs that must track the code, skip the Wiki and keep Markdown in /docs, reviewed in pull requests.

Common Mistakes

Putting API docs in the Wiki — it is not reviewed in pull requests, so it silently drifts from the code it describes.
Using absolute github.com URLs for in-repo README links — they break in forks and after a rename, where relative links survive.
Enabling Pages from a branch that also holds app code — every push redeploys the site and mixes build artifacts into source.
Skipping SECURITY.md — vulnerability reports land in public issues instead of a private disclosure channel.
Assuming a custom Pages domain is secure by default — without "Enforce HTTPS" checked it serves plain HTTP.

Best Practices

Keep docs that must match the code in /docs, reviewed in the same pull request as the change.
Use relative links in the README so they survive forks and renames.
Deploy GitHub Pages via an Actions workflow rather than a branch when there is a build step.
Add SECURITY.md to route vulnerability reports to a private advisory instead of public issues.
Check "Enforce HTTPS" on any Pages site, especially one with a custom domain.

Comparable toolsGitLab Wiki plus PagesBitbucket Wiki and integrationsGitea Wiki and Pages-style hostingRead the Docs hosted documentation sites

Knowledge Check

Why does API documentation drift when it lives in the Wiki?

The Wiki is a separate repo not reviewed in the code's pull requests, so nothing ties its updates to the code
Wikis become read-only the very moment a page is published, so the docs freeze in place and fall behind the code
GitHub deletes every Wiki page automatically after each tagged release of the repo
Wikis cannot render fenced code blocks, so API examples never display correctly

Why use relative links instead of absolute github.com URLs in a README?

Relative links keep working in forks and after the repo is renamed; absolute URLs break in both cases
Absolute URLs are not valid Markdown syntax, so GitHub refuses to render them in a README
Relative links load noticeably faster on the repo home page than absolute ones
GitHub strips absolute URLs out of READMEs as a built-in security measure whenever the page is rendered for a viewer

What does adding SECURITY.md change about vulnerability reports?

It routes reporters to a private disclosure channel instead of leaving them to file a public issue
It automatically patches known vulnerabilities in the repo's dependencies as they are disclosed
It hides the repository from search engines until the listed issues are resolved
It requires every single pull request to pass an automated security scan before it can ever be merged in

When should Pages deploy from an Actions workflow rather than a branch?

When there is a build step, so built output stays out of your source branches
Always, since branch-based deployment has been removed from Pages entirely
Only for private repositories, where branch deployment is not available
Never, because Actions workflows are not able to publish to Pages

You got correct