Why the GitHub Wiki is an Anti-Pattern (2022)

Every six months or so, a familiar debate resurfaces in the developer community: “Should I utilize the built-in GitHub wiki or simply create a /docs folder within my repository?”

Following the logic of Shawn Wang’s "three strikes rule," I decided it was time to formalize my thoughts on this subject.

Initially, I intended to start this piece by saying, "You can use the wiki or a docs folder for your GitHub project, both are valid choices."

However, as I delved deeper into the analysis, I realized there is only one solitary reason to use a wiki, while the reasons to avoid it are numerous. Consequently, I now believe that employing the GitHub wiki is an anti-pattern.

The Comparison: Wiki vs. /docs Folder

To illustrate the disparity, let's look at the trade-offs:

The "Pros" of the Wiki

The list of benefits is incredibly short:

1. You can access the wiki content with a single click from anywhere in the repository.
2. There is no number two.

Essentially, the only advantage is that the wiki is "always there."

The "Pros" of the /docs Folder

Conversely, keeping documentation in a folder provides significant technical advantages:

• Synchronized Versioning: Documentation evolves alongside the code. If you need to reference docs for an older version of the software, they are right there.
• Local Access: When a user clones the repo, the docs are available offline (unlike the wiki, which requires a separate, often hidden, clone process).
• Quality Control: Edits undergo the same rigorous pull request process as code, allowing for full peer review.
• Automation: You can integrate GitHub Actions to run linting tools like Vale.
• Developer Experience: Contributors can use their preferred tools, such as VS Code with integrated spellcheck.

Implementation Strategy

If you are convinced that docs belong with the code, you might wonder how to make them easily viewable.

Warning: $\text{Do NOT use the } \texttt{gh-pages} \text{ branch}$, as this breaks the ability to version docs alongside the code.

Instead, follow this checklist:

• Set up a GitHub Pages build to publish your documentation.
• For beginners: Use the just-the-docs theme for a seamless build/publish experience.
• For advanced users: Build a custom workflow (e.g., using Hugo) via a GitHub Action.
• Create a single, solitary wiki page that redirects users to your hosted documentation.

For those using a custom action, your workflow might look something like this:

name: Deploy Docs
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Build Hugo Site
        run: hugo --minify
      - name: Deploy to GH Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

The Long-term Evolution

When starting a new product, the /docs folder represents a specific balance of effort and reward. We can express this as:

$\text{Value} = \frac{\text{Reward}}{\text{Effort}}$

Eventually, your documentation will grow too large for a single folder. At that stage, the architecture must change. You will likely move to a dedicated repository with its own:

• Build pipeline.
• PR review guidelines.
• Specialized management tools.

Because your contributors are already accustomed to managing documentation within a repository (thanks to the /docs approach), the transition to a separate repo is seamless.

Documentation Lifecycle Flow

---

Whether you agree or disagree with this stance, I would love to hear your perspective on Twitter!