The GitHub wiki is an anti-pattern
If you need to use an old version, the docs are easy to findThe documentation isn’t available locally when someone clones your repo (you can clone the wiki separately, but this is a hidden feature)Documentation edits get the same treatment as code. They get a full peer review through the pull request processYou can use GitHub Actions to lint your docs using tools such as ValePeople can work with tooling that they already know (e.g. vscode with spellcheck)Wikis provide limited branding opportunities. They all look pretty much the sameThe wiki doesn’t support image uploads, so you have to put images somewhere else anywayNow that you’re sold on the idea of keeping docs alongside your code, how do you make it easy for people to view them?Add your docs to your repository in the /docs folder.
- ▪If you need to use an old version, the docs are easy to findThe documentation isn’t available locally when someone clones your repo (you can clone the wiki separately, but this is a hidden feature)Documentation edits get the same treatment
- ▪They get a full peer review through the pull request processYou can use GitHub Actions to lint your docs using tools such as ValePeople can work with tooling that they already know (e.g. vscode with spellcheck)Wikis provide limited branding
- ▪They all look pretty much the sameThe wiki doesn’t support image uploads, so you have to put images somewhere else anywayNow that you’re sold on the idea of keeping docs alongside your code, how do you make it easy for people to view them?A
Hacker News (Front Page) files mainly under programming. We currently carry 2,039 of its stories. Top-voted stories on Hacker News.
Story provenance
Source · retrieval · rights · ranking — open for full record
inspect →
Story provenance
Attribution is not the same as permission. This drawer separates discovery metadata, excerpts, WeSearch-generated summaries, reuse status, and whether the publisher receives the visit. Nothing here claims a legal grant the publisher has not made.
Record
| Original publisher | michaelheap.com |
| Canonical URL | https://michaelheap.com/github-wiki-is-an-antipattern/ |
| Publication time | Wed, 23 Sep 2026 13:05:49 +0000 |
| Retrieval time | 2026-09-23T13:39:30.794Z |
| Last seen | 2026-09-23T13:39:30.794Z |
| Headline source | Publisher (no WeSearch rewrite) |
| Excerpt source | publisher body |
| Excerpt method | First ~120 words (~800 chars) of extracted publisher body, fair-use limited. |
| Summary | WeSearch · cerebras-chat (WeSearch summarizer) |
| Summary source text | contentText |
| Citation coverage | Summary is a WeSearch-generated derivative; primary citation is the original publisher URL. |
| Cluster | Uy3upqPRj4tG · 1 stories |
| Cluster logic | Grouped by semantic title/content similarity across sources within a rolling window. Same-publisher template collisions are excluded from coverage comparison. |
| Ranking reason | Story pages are not engagement-ranked. Hub feeds use recency, with optional source-diversified chronological ordering (cap consecutive stories per source). No personalized ranking. |
| Publisher visit | Yes — open original |
| Substitutes article? | No — link-out required for full text |
Rights status (four layers)
WeSearch handling by dimension
| Indexing | May the item be indexed (stored, ranked, made findable)? | Allowed |
| Snippet | May a short excerpt of the publisher's text be shown? | Allowed |
| AI summary | May WeSearch generate its own short summary of the article? | Limited |
| Retrieval / RAG | May the content be exposed for third-party retrieval-augmented generation? | Not asserted |
| Model training | May the content be used to train AI models? | Not asserted |
| Commercial reuse | May the content be reused commercially? | Not permitted |
Basis: Derived from the published RSS/Atom feed. Contact: [email protected]. Reviewed: 2026-07-24.
Opening excerpt (first ~120 words) tap to expand
❤️ #github #opinion AIL: 0The GitHub wiki is an anti-pattern23 Jan 2022 in TechThe “should I use the wiki or a docs folder on GitHub?” discussion comes up every 6 months or so, and following Shawn Wang’s three strikes rule I thought it was about time I wrote something down about it.The initial version of this post opened with “You can use the wiki or a docs folder for your GitHub project, both are valid choices” but as I wrote more, I realised that there is a single reason to use a wiki, and many more reasons not to use the wiki.
…
Excerpt limited to ~120 words for fair-use compliance. The full article is at michaelheap.com.
Discussion
0 commentsMore from michaelheap.com
