<!-- mobian-agent-page publisher="dailydev" canonical="https://daily.dev/posts/the-github-wiki-is-an-anti-pattern-1xoqzltfd" -->

---
title: The GitHub wiki is an anti-pattern | daily.dev
description: An argument against using GitHub wikis for project documentation, favoring a /docs folder in the repository instead. The reasoning covers version control...
canonical: https://daily.dev/posts/the-github-wiki-is-an-anti-pattern-1xoqzltfd
twitter:card: summary_large_image
twitter:site: @dailydotdev
og:type: website
og:site_name: daily.dev
og:title: The GitHub wiki is an anti-pattern | daily.dev
og:description: An argument against using GitHub wikis for project documentation, favoring a /docs folder in the repository instead. The reasoning covers version control...
og:url: https://daily.dev/posts/the-github-wiki-is-an-anti-pattern-1xoqzltfd
og:image: https://api.daily.dev/og/posts/1xOQzLtfd.png
og:image:alt: The GitHub wiki is an anti-pattern
og:image:width: 1200
og:image:height: 630
og:locale: en
---

> ## Documentation Index
> Fetch the complete documentation index at: https://daily.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# The GitHub wiki is an anti-pattern

**[Lobsters](https://daily.dev/sources/lobsters)** · 3 min read · 0 upvotes · 0 comments

## Summary

An argument against using GitHub wikis for project documentation, favoring a /docs folder in the repository instead. The reasoning covers version control alongside code, availability when cloning locally, peer review via pull requests, linting with tools like Vale, familiar tooling for contributors, and better branding and image support. The author recommends publishing docs via GitHub Pages using themes like just-the-docs or custom Hugo workflows, and suggests leaving a single wiki page pointing to the hosted docs.

## Full article

daily.dev links to this article rather than hosting it. Read it at the original source: <https://michaelheap.com/github-wiki-is-an-antipattern>

## Questions this post answers

### Should I use a GitHub wiki or a docs folder for my project's documentation?

A docs folder in the repository is generally better than a GitHub wiki. It keeps documentation versioned alongside code, available when the repo is cloned, subject to pull request review, lintable with tools like Vale, and editable with familiar tools such as VS Code with spellcheck, whereas wikis lack these and don't support image uploads.

_daily.dev surfaces practical takes like this for developers deciding how to structure project documentation._

### How do I publish documentation from a /docs folder using GitHub Pages?

Add documentation files to a /docs folder in the repository rather than the gh-pages branch, so docs stay versioned with the code, then configure a GitHub Pages build to publish them. Beginners can use the just-the-docs theme and let GitHub build and publish automatically; those wanting a custom workflow, such as with Hugo, can use the actions-gh-pages GitHub Action.

_Developers setting up docs sites can find setup guidance like this through daily.dev._

## Community take

How the wider developer community reacted, aggregated from 2 discussions and 184 comments across lobsters, hackernews (as of 2026-09-24).

**TL;DR:** Discussion is split: many agree that versioning docs alongside code (via a /docs folder) beats GitHub wikis for review and staleness, but a large contingent pushes back that wikis' low-friction editing is their whole point and that the post doesn't address that tradeoff at all.

**Sentiment:** 30% positive · 50% mixed · 20% skeptical

**The case for**

- Keeping docs in the repo lets changes be reviewed and tracked with git blame/history the same way as code.
- A /docs folder avoids code-doc drift better since PRs surface missing doc updates next to the diff.
- Other systems like Fossil or Forgejo already version wikis natively, showing the underlying idea has merit.
- Generating a branded site from /docs (e.g. via Sphinx or Hugo) gives nicer rendering than GitHub's plain wiki styling.

**The pushback**

- The post ignores that wikis' core value is frictionless editing without needing a PR, commit, or code-review process.
- Requiring review/CI for every doc change creates friction that discourages contributors from fixing typos or improving docs at all.
- GitHub wikis are excluded from search engine indexing, which undermines their discoverability regardless of format.
- Non-technical people can't easily use git/PR workflows, limiting who can contribute to /docs versus a wiki.
- Docs that aren't tied to a specific code change (broad system overviews, scratchpads) don't fit neatly into a per-PR review model.

**By community**

- lobsters (mixed): People largely agree with versioning benefits but push back hard on the claim that PR review is unambiguously better than a wiki's free-editing model, plus note the little-known fact that GitHub wikis are blocked from search indexing.
- hackernews (heated): A large, contentious thread mixes agreement that /docs improves doc-code sync with strong pushback that mandatory PR review adds friction that kills casual doc contributions, alongside a long tangential debate about monorepos vs polyrepos and alternatives like Fossil.

**Hottest debate:** Whether requiring PR/code review for documentation edits is a net benefit (better sync, less rot) or a harmful friction that discourages contributions compared to a wiki's frictionless editing.

**Open questions**

- How should teams route or relax review/CI requirements specifically for docs-only changes?
- How do you handle binary assets (images, PDFs, spreadsheets) that don't fit naturally into a markdown /docs folder?
- At what point does a docs folder actually 'outgrow' a single repo, and what specifically breaks at that scale?

**Highlights**

> I think there is a missing pro here on the wiki side: trivial edits are trivial. Even fixing a typo in the docs directory requires PR + approvals + CI. Effectively limiting your docs contributors to folks who are comfortable with a code editor, and git, is a decision
> — [swiftcoder on hackernews · 1 comments](https://news.ycombinator.com/item?id=49816885)

> > 3. Documentation edits get the same treatment as code. They get a full peer review through the pull request process. Well, that's the main difference, and the key benefit of wikis: they're open for immediate edits and don't require pre-review. YMMV on whether this works for your project or community, some people love it because it enables and empowers other contributors to just document things, while others (reasonably) want to mandate pre-review with careful curation.
> — [legoktm on lobsters · 6 points, 1 comments](https://lobste.rs/s/d339rn/github_wiki_is_anti_pattern#c_dfqand)

> Biggest thing for me is wiki edits skip code review, so docs rot silently while a /docs PR at least shows up in the diff next to the change.
> — [hn1rig3rak on hackernews · 2 comments](https://news.ycombinator.com/item?id=49815861)

> I disagree, requiring code review for docs changes sounds great but in my experience it's extremely hard to get a human to review docs changes. Either you get a rubber stamp with no real review (zero added value, adds useless friction) or you spend days bugging people to actually review your changes. All for docs! The counter-argument i envision is: "update your docs and code at the same time in the same PR!" That works great, until you want to document something that isn't precisely tied to a single piece of code. In fact I think the most useful docs describe high level systems rather than being associated with specific pieces of code. Use comments for that; in contrast, docs should be easily editable by anyone at all times, otherwise they never get updated (an evergreen problem in any scenario).
> — [ericyd on hackernews · 1 comments](https://news.ycombinator.com/item?id=49821023)

**Source threads**

- [lobsters](https://lobste.rs/s/d339rn/github_wiki_is_anti_pattern) · 33 points · 14 comments
- [hackernews](https://news.ycombinator.com/item?id=49815484) · 115 points · 170 comments

## Similar posts on daily.dev

- [It's time to move your docs in the repo](https://daily.dev/posts/it-s-time-to-move-your-docs-in-the-repo-5ncacizen) · Hacker News · 1 upvotes · 0 comments
- [What's Wrong with GitHub](https://daily.dev/posts/what-s-wrong-with-github-d9tpnmdyq) · Lobsters · 0 upvotes · 0 comments
- [Talk to your documentation](https://daily.dev/posts/talk-to-your-documentation-clrd99amx) · The Art of Simplicity · 0 upvotes · 0 comments
- [From Decentralized Docs-as-Code to a Centralized Repository: Evolving Grab's Documentation Strategy](https://daily.dev/posts/from-decentralized-docs-as-code-to-a-centralized-repository-evolving-grab-s-documentation-strategy-h0aan4e9b) · Grab Tech Blog · 0 upvotes · 0 comments
- [𝕯𝖔𝖈 𝖎𝖙 𝖑𝖎𝖐𝖊 𝖎𝖙'𝖘 𝖍𝖔𝖙](https://daily.dev/posts/vzncwvvm8) · Planet Haskell · 1 upvotes · 0 comments

---

Tags: [#open-source](https://daily.dev/tags/open-source), [#github](https://daily.dev/tags/github), [#github-pages](https://daily.dev/tags/github-pages)

[View this post on daily.dev](https://daily.dev/posts/the-github-wiki-is-an-anti-pattern-1xoqzltfd)

```json
{"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://daily.dev/#organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180},"sameAs":["https://twitter.com/dailydotdev","https://github.com/dailydotdev","https://www.linkedin.com/company/daily-dev-ltd"]},{"@type":"WebSite","@id":"https://daily.dev/#website","url":"https://daily.dev","name":"daily.dev","publisher":{"@id":"https://daily.dev/#organization"},"potentialAction":{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https://daily.dev/search?q={search_term_string}"},"query-input":"required name=search_term_string"}}]}
{"@context":"https://schema.org","@type":"TechArticle","headline":"The GitHub wiki is an anti-pattern","url":"https://daily.dev/posts/the-github-wiki-is-an-anti-pattern-1xoqzltfd","mainEntityOfPage":{"@type":"WebPage","@id":"https://daily.dev/posts/the-github-wiki-is-an-anti-pattern-1xoqzltfd"},"datePublished":"2026-09-23T16:44:22.059Z","dateModified":"2026-09-24T00:00:43.296Z","description":"An argument against using GitHub wikis for project documentation, favoring a /docs folder in the repository instead. The reasoning covers version control...","image":"https://media.daily.dev/image/upload/f_auto,q_auto/v1/posts/48f6f0e47a31ad06e03eb9a6c352d74b?_a=AQAEuop","thumbnailUrl":"https://media.daily.dev/image/upload/f_auto,q_auto/v1/posts/48f6f0e47a31ad06e03eb9a6c352d74b?_a=AQAEuop","isAccessibleForFree":true,"articleSection":"Lobsters","inLanguage":"en","publisher":{"@type":"Organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180}},"author":{"@type":"Organization","name":"Lobsters","logo":"https://media.daily.dev/image/upload/s--tl8v_Fku--/f_auto,t_logo/v1698841318/logos/lobste.jpg","url":"https://daily.dev/sources/lobsters"},"commentCount":0,"discussionUrl":"https://daily.dev/posts/the-github-wiki-is-an-anti-pattern-1xoqzltfd","interactionStatistic":[{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":0},{"@type":"InteractionCounter","interactionType":{"@type":"CommentAction"},"userInteractionCount":0}],"keywords":"open-source,github,github-pages","timeRequired":"PT3M"}
{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://daily.dev"},{"@type":"ListItem","position":2,"name":"Lobsters","item":"https://daily.dev/sources/lobsters"},{"@type":"ListItem","position":3,"name":"The GitHub wiki is an anti-pattern"}]}
{"@context":"https://schema.org","@type":"FAQPage","@id":"https://daily.dev/posts/the-github-wiki-is-an-anti-pattern-1xoqzltfd#faq","mainEntity":[{"@type":"Question","name":"Should I use a GitHub wiki or a docs folder for my project's documentation?","acceptedAnswer":{"@type":"Answer","text":"A docs folder in the repository is generally better than a GitHub wiki. It keeps documentation versioned alongside code, available when the repo is cloned, subject to pull request review, lintable with tools like Vale, and editable with familiar tools such as VS Code with spellcheck, whereas wikis lack these and don't support image uploads. daily.dev surfaces practical takes like this for developers deciding how to structure project documentation."}},{"@type":"Question","name":"How do I publish documentation from a /docs folder using GitHub Pages?","acceptedAnswer":{"@type":"Answer","text":"Add documentation files to a /docs folder in the repository rather than the gh-pages branch, so docs stay versioned with the code, then configure a GitHub Pages build to publish them. Beginners can use the just-the-docs theme and let GitHub build and publish automatically; those wanting a custom workflow, such as with Hugo, can use the actions-gh-pages GitHub Action. Developers setting up docs sites can find setup guidance like this through daily.dev."}}]}
```

