Every Programmer Should Know — Admin Guide

Operational reference for maintainers, contributors, and anyone forking github.com/mtdvio/every-programmer-should-know. This is a content-only repository — a curated Markdown list — so "admin" here means curation, contribution review, repository hygiene, and fork maintenance rather than deployment or runtime operations.

1. Executive Summary

Every Programmer Should Know is a single-page curated list of technical and career resources for working programmers, published as a GitHub repository and maintained by Dmitri Grabov (@mtdvio). The repository ships three files: README.md (the list), CONTRIBUTING.md (the rules), and LICENSE (MIT).

There is no application, no build, no CI. The deliverable is prose. The operational questions are therefore:

• Who decides what goes in?
• How do pull requests get reviewed?
• How are broken links and translation requests handled?
• How do you fork this responsibly?

This guide answers those questions using only what is in the repository today.

Note

If you are looking for how to use the list as a reader, see the User Guide. This document is for the people keeping the list alive.

2. Repository Architecture

2.1 Layout

every-programmer-should-know/
├── CONTRIBUTING.md    ← curation rules, values, emoji vocabulary
├── LICENSE            ← MIT, Copyright (c) 2017 Dmitry Grabov
├── README.md          ← the list: ~22 KB, ~30 sections, ~250 entries
└── .github/           ← community health files (issue templates, etc.)

Three tracked files drive everything. Every piece of value in this project lives in README.md.

2.2 Conceptual model

               Reader
                 |
                 v
        +---------------+
        |   README.md   |   curated list (one file)
        +---------------+
                 ^
                 |  accepted PR
                 |
        +---------------+       PR / issue
        |   Contributor |----------------------+
        +---------------+                      |
                                               v
                                     +-------------------+
                                     |     Maintainer    |
                                     |   (@mtdvio)       |
                                     | applies curation  |
                                     |     values        |
                                     +-------------------+
                                               ^
                                               |
                                   +-----------------------+
                                   |   CONTRIBUTING.md     |
                                   | (values + guidelines) |
                                   +-----------------------+

CONTRIBUTING.md is the explicit policy document. README.md is the artifact. The maintainer is the gatekeeper. There is no automation — no linter, no link checker, no bot — in the repository today.

2.3 What this repository does not have

Be explicit about what is absent so you don't go looking:

• No package or build (package.json, Cargo.toml, requirements.txt, Makefile, etc.).
• No CI/CD config (.github/workflows/, .gitlab-ci.yml, etc.) in the tracked content.
• No linter or formatter config (.markdownlint.json, .prettierrc, etc.).
• No test suite.
• No dependencies.
• No runtime.
• No automated link checker. Broken links are triaged manually via GitHub issues.
• No canonical translations. Requests (e.g. the closed issue #219 asking for Brazilian Portuguese) have historically been declined.
• No generated static site. The repository is consumed directly through GitHub's rendered Markdown.

Important

This minimalism is a design decision, not an oversight. The list is small enough that automation would add more overhead than it removes. Do not add CI unless a concrete pain point justifies it.

3. System Requirements

To work as a maintainer or contributor you need only:

Everything else is convenience. Common conveniences:

• A link checker you run locally before opening a PR (e.g. lychee, markdown-link-check). Not required, not tracked in-repo.
• A Markdown linter (markdownlint). Not required.

macOS / Linux

git clone https://github.com/mtdvio/every-programmer-should-know.git
cd every-programmer-should-know

Cloning into 'every-programmer-should-know'...

Windows (Git Bash)

git clone https://github.com/mtdvio/every-programmer-should-know.git
cd every-programmer-should-know

Cloning into 'every-programmer-should-know'...

Tip

The full repository is under 50 KB. You can keep a working copy anywhere with negligible cost.

4. Curation Philosophy (Policy Reference)

This is the single most important section for anyone reviewing or proposing changes. The policy is set in CONTRIBUTING.md and maintainers are expected to apply it verbatim, not their own judgment.

4.1 The stated goal

Our goal is not to have the biggest list of stuff. Our goal is to have a comprehensible list of most valuable things any programmer should know about.

Two consequences for reviewers:

• Bigger is not better. "This list doesn't cover X" is not automatically a reason to add X.
• "Comprehensible" beats "comprehensive." If a new entry makes a section harder to skim, it is probably a net negative even if it is high quality on its own.

4.2 The four core values

Taken directly from CONTRIBUTING.md:

Important

When triaging a PR, cite the specific value that applies. "Fails value #3 (adds to hype)" gives the contributor a concrete reason and keeps the project's rules visible.

4.3 The contributor guidelines

Four explicit rules for PR authors, lifted from CONTRIBUTING.md:

1. Do not add things you have not evaluated personally. You must have read the book, watched the talk, worked through the article. Taste as a service, not link collection.
2. Use reasoning based on the core values. A good PR description explicitly answers: will this make a programmer better at their work, better in their life, a better human?
3. One item per pull request. Makes review, discussion, and revert trivial.
4. Do not open issues with resources, create a pull request instead. Issues are for discussion; PRs are the proposal format.

Note

Rule #4 is sometimes violated — the issue tracker has several "what about X" threads (e.g. #42 Problem Solving, #123 Network). Maintainers routinely redirect these to PRs.

4.4 Emoji vocabulary (enforced)

Only five emojis carry documented semantic weight:

Contributors occasionally use others (:link:, :school:, :moneybag:, :zap:, :fire:, :heart:, :globe_with_meridians:, :newspaper:, :hammer:). These have accumulated organically and are treated as curator emphasis rather than categorical signals. Reviewers should not reject PRs solely for using them if the primary vocabulary is also present — but pushing authors toward the documented five keeps the list scannable.

4.5 No PR silently dropped

The policy document makes one unusual promise:

No PR will be discarded without explanations!

Maintainers must leave a comment on every rejection. "No" is fine; "no, because it conflicts with value #3" is the expected form. This is a user-visible commitment; do not let PRs rot without a reply.

5. Contribution Workflow

5.1 Inbound PR checklist (for maintainers)

Work through this list for every PR:

• [ ] Scope: exactly one resource added or modified? (Guideline #3.)
• [ ] Evaluation: does the PR description indicate the author evaluated the resource? (Guideline #1.)
• [ ] Value fit: does the resource match at least one of the four core values? Is it free of hype/stress-inducing content? (Values #1–#4.)
• [ ] Section fit: is the new entry placed in a sensible existing section? If the author created a new section, does the topic really warrant one? (History shows new sections are rare and require the topic to be mature — Platform Engineering is the most recent example.)
• [ ] Emoji: correct resource-type emoji from the documented five? (Other emojis allowed but not preferred.)
• [ ] Link health: does the target URL load? Does it match the claimed title? Is it canonical (not a mirror or cached copy unless the canonical is dead)?
• [ ] Formatting: plain Markdown bullet, no inline HTML, no broken list indentation. Short annotation if the title is not self-describing.
• [ ] Duplication: is this resource (or a near equivalent) already in the list elsewhere? The Memory section deliberately lists Drepper's What Every Programmer Should Know About Memory twice (Memory + Papers) as a curated exception; that is unusual.
• [ ] Tone: neutral, descriptive. No marketing copy from the linked resource.

5.2 Merging

Maintainer merges directly to master. There is no protected-branch review policy in the repository today. This is feasible because:

• The maintainer is the sole reviewer by design.
• Every change is small (one bullet).
• Revert is trivial (git revert) if a merged PR later proves regrettable.

Caution

If you ever add more maintainers, add branch protection and require one approving review. Without it, the curation-consistency that is the entire product value is one bad merge away from erosion.

5.3 Rejection template

Short, kind, policy-anchored. A reusable template:

Thanks for the contribution!

I'm going to pass on this one because it conflicts with our
**{value name}** value — specifically, {one-sentence reason}.

For reference, our curation values live in
[CONTRIBUTING.md](./CONTRIBUTING.md#core-values).

(Keep the PR open for a day or two in case anyone wants to discuss.)

Note

The project's explicit rule is that no PR is closed without explanation. A one-line rejection is a policy violation, not a time-saver.

5.4 Issue triage

The repository uses GitHub Issues lightly. Known ongoing issue categories, with live examples:

Recommended triage order, fastest-to-slowest to close:

1. Broken links. Either accept a fix PR, or replace with a Wayback/canonical URL yourself and close. Low-controversy, user-visible value.
2. New-resource feature requests. Redirect to a PR per guideline #4, close the issue.
3. New-section requests. Leave open until the underlying topic is clearly mature and there is at least one concrete resource proposed.
4. Translations. The project position, based on the history of issue #219, is to not fork translations into the canonical repo. Point contributors to the MIT license and encourage them to maintain a fork.

6. Operations

6.1 Start / stop / logs

There is no service to start, stop, or log. The repository is static content served by GitHub. "Operations" for a content repo consists of publishing commits and responding to incoming PRs/issues.

6.2 Publishing a change

From GitHub UI

1. Edit README.md in the GitHub web editor (pencil icon).
2. Commit directly to a new branch, e.g. add-<resource-slug>.
3. Open a PR against master.
4. Merge after review.

From local clone

git checkout -b add-<resource-slug>
# edit README.md
git add README.md
git commit -m "Add <Resource Name> to <Section>"
git push origin add-<resource-slug>

To github.com:mtdvio/every-programmer-should-know.git
 * [new branch]      add-<resource-slug> -> add-<resource-slug>

Open a PR via gh pr create or the GitHub UI.

Commit message convention (inferred from repository history — not codified): Add <Resource Name> or Fix broken link: <Resource Name>.

6.3 Backups

GitHub retains history. A local mirror clone is trivial insurance:

git clone --mirror https://github.com/mtdvio/every-programmer-should-know.git

Cloning into bare repository 'every-programmer-should-know.git'...

Store the resulting .git directory anywhere. To refresh:

cd every-programmer-should-know.git
git remote update

Note

For a content repo this size, a monthly manual mirror is overkill for safety and underkill for anything else. One-time + occasional pulls is enough.

6.4 Monitoring

There is nothing to monitor on the repository itself. What you can monitor:

• The Issues tab — incoming broken-link reports and feature requests.
• The Pull Requests tab — incoming contributions awaiting review.
• The repository's Insights → Traffic page (maintainer-only) — reader traffic and referrers.

A reasonable cadence is a weekly check of open issues/PRs and a monthly check of traffic.

6.5 Link rot

This is the most common long-term maintenance burden. The list has ~250 outbound links; some will break every year. Options:

• Reactive (current approach): fix when a user reports an issue like #731.
• Proactive: run a link checker quarterly. Example tools:

# lychee — single-binary Rust link checker
lychee README.md

Total .........: 254
Successful ....: 241
Errors ........: 13

Reacting to link rot is usually correct for a repo this small. Running a checker quarterly and opening a single consolidated PR is a reasonable upgrade if the issue tracker is getting noisy.

7. Security

7.1 Threat model

A curated-list repository has a small attack surface, but it is not zero.

Warning

The reviewer is the security boundary. A PR that adds a bullet to a list looks harmless, which is exactly why a malicious link is plausible. Always click through.

7.2 Credential and secret surface

There are no secrets in the repository. No .env, no API keys, no tokens. If a PR ever adds one, reject it and audit the commit history.

7.3 GitHub repository security

Recommended settings (check with the GitHub UI; these are not enforceable from the repo contents):

• [ ] Two-factor auth required on the maintainer's account.
• [ ] SSH keys rotated on any suspicion of compromise.
• [ ] Branch protection on master if/when a second maintainer is added.
• [ ] Dependabot / security advisories: not applicable (no dependencies).
• [ ] Secret scanning: enabled (default on public repos) — free safety net.

7.4 Disclosed sponsorship

The README.md opens with a promotional banner for mylevel.dev, disclosed as "Created by this repo author". This is the maintainer's own project, not a third-party ad slot. For governance transparency:

• Disclosure is present.
• The banner is in the repository, under the maintainer's control, not injected by an external network.
• It does not appear as a curated entry inside the list itself.

If the list ever starts accepting paid placement, document it in CONTRIBUTING.md and mark paid entries explicitly. Today, that is not the case.

8. Performance and Scale

The repository serves static Markdown via GitHub. Scale properties:

There is no performance tuning to do. The scaling lever is curation discipline, not infrastructure.

Tip

If the list ever grows enough that readers report skimmability problems, consider splitting long sections into sub-lists in the same file before splitting into multiple files. Multiple files break the "one artifact" simplicity that makes this project easy to use and maintain.

9. Forking and Customization

The MIT license permits forking for any purpose. A common use: a company or team maintains an internal version pruned to their stack and topped with company-specific resources.

9.1 When to fork

• You want to remove sections your audience doesn't need.
• You want to add company-specific or stack-specific material the upstream would reject (too niche, too promotional, too language-specific).
• You want editorial control — different curation values than mtdvio.

9.2 Fork workflow

# 1. Fork on GitHub via the UI, then:
git clone git@github.com:<your-org>/every-programmer-should-know.git
cd every-programmer-should-know

# 2. Add upstream so you can pull updates:
git remote add upstream https://github.com/mtdvio/every-programmer-should-know.git

# 3. Periodically sync (be selective — not every upstream change fits your fork):
git fetch upstream
git log upstream/master --oneline --since="3 months ago" -- README.md

a1b2c3d Add <Resource> to <Section>
...

Cherry-pick interesting commits:

git cherry-pick a1b2c3d

9.3 Documenting your divergence

Update your fork's CONTRIBUTING.md to reflect your own curation values (which may differ from the upstream's). Keep the MIT license. Credit the upstream in README.md's header — the license requires preserving copyright, but courtesy says you should also link back visibly.

9.4 Contributing back

If a fork improvement is general-purpose, open an upstream PR. Internal/company-specific additions stay in the fork; don't try to push them upstream.

10. Troubleshooting

10.1 "A submitted PR has been sitting for weeks."

Cause: maintainer bandwidth. This is a single-maintainer, no-SLA project.

Resolution (for contributors): gentle ping after two weeks. Don't escalate. If you have an urgent need, fork and maintain your own copy.

Resolution (for maintainer): batch reviews weekly. Even a rejection with a reason (per §5.3) keeps the project's "no silent close" promise and is cheap to write.

10.2 "A merged link is dead / wrong."

Cause: link rot (normal over years) or the PR description did not match the actual target.

Resolution: open an issue or PR with the corrected URL. Historical examples of the correction workflow: #186, #214. For a fast fix, Wayback-Machine-capture the original, then replace with the capture URL if the resource is truly gone.

10.3 "Two entries link to essentially the same resource."

Cause: either (a) deliberate curation (e.g. Memory section lists Drepper twice — once in Memory, once in Papers on Programming), or (b) an accidental duplicate.

Resolution: before opening a deduplication PR, check whether the duplicate is in two different sections with different intent. If so, it's intentional. If they're in the same section, open a PR removing one.

10.4 "A contributor disputes a rejection."

Cause: curation is subjective and values can be interpreted differently.

Resolution: cite the specific value from CONTRIBUTING.md. If the dispute is genuinely about the interpretation of a value, that is an opportunity to sharpen the policy — update CONTRIBUTING.md if needed and link the PR to the new wording. Do not litigate on taste alone.

10.5 "Someone opened an issue with a wall of resources."

Cause: guideline #4 ("Do not open issues with resources, create a Pull Request instead!") is being ignored.

Resolution: politely redirect to a PR, one item per PR (guideline #3). Close the issue with a link to the guidelines. The canonical examples of this redirect pattern live in the project's older threads.

10.6 "A section feels out of date."

Cause: a topic area has moved faster than the list has been maintained (e.g. Machine Learning, where a single Andrew Ng course is the only entry despite the field's explosion).

Resolution: this is deliberate — see core value #1, "Less is more." A PR replacing the existing resource with a better single resource is welcome; a PR adding eight new ones is not. Discuss in an issue first if the right answer is unclear.

10.7 "Translations keep getting requested."

Cause: the project is popular enough that non-English-speaking readers want localized copies.

Resolution: the project position (based on #219) is that the canonical list stays English. Point contributors to the MIT license and suggest a translated fork. Link the fork from the upstream README.md only if it is actively maintained.

10.8 "An added resource has a shortened URL."

Cause: contributor pasted a shortened link (bit.ly, t.co, etc.).

Resolution: ask for the canonical URL. Shorteners obscure the destination, interfere with link checking, and go dark when the shortener service does.

10.9 "A resource is behind a paywall."

Cause: many books link to Goodreads; some articles are on paywalled publications (ACM, journals).

Resolution: acceptable. The list does not promise free resources — the Free Books on Programming section explicitly delegates free-title curation to the EbookFoundation/free-programming-books project. Prefer Goodreads or a publisher page for books (neutral, evaluable). Prefer open alternatives where they exist with equal quality.

10.10 "Everything looks fine but GitHub's rendered view shows broken Markdown."

Cause: unescaped inline HTML, a stray < or >, or a malformed emoji shortcode.

Resolution: preview locally with any GitHub-flavored Markdown renderer (VS Code, Obsidian, grip). Diff against the previous rendering. The issue is almost always in the most recent commit.

pip install grip
grip README.md

 * Serving Flask app 'grip'
 * Running on http://localhost:6419/

11. Reference

11.1 File inventory

11.2 License

MIT. Copyright (c) 2017 Dmitry Grabov. Standard permissive terms: use, copy, modify, merge, publish, distribute, sublicense, and sell, with attribution and no warranty.

Operational implications:

• Forks are permitted for any purpose, including commercial.
• You must keep the copyright notice in redistributions.
• The project comes with no warranty — a dead link has no remedy.

11.3 Contact

• Maintainer: @mtdvio on GitHub
• Issue tracker: github.com/mtdvio/every-programmer-should-know/issues
• Pull requests: github.com/mtdvio/every-programmer-should-know/pulls
• There is no email, Slack, or Discord channel for the project.

11.4 Related upstreams / downstreams

• Peers (similar curation, different scope): sindresorhus/awesome (meta-list); papers-we-love/papers-we-love (papers only); 97-things/97-things-every-programmer-should-know (referenced from the Career section).
• Delegated domains: EbookFoundation/free-programming-books for free titles; kamranahmedse/developer-roadmap for visual roadmaps.
• Translations: no canonical list. Check the fork network if you need a translated copy.

11.5 Potential improvements (for future maintainers)

These are suggestions, not commitments. Evaluate each against the "less is more" value before acting.

• Add a link-checker GitHub Action. Quarterly run, opens a single issue with all broken links. Justification: link rot is the dominant maintenance cost; automating detection does not violate the minimalism rule because it runs only as maintainer tooling, not as repository product.
• Publish a changelog. A CHANGELOG.md enumerating newly added and removed resources per year. Useful for returning readers. Keeps history grep-friendly.
• Add a TOC to README.md. GitHub generates its own right-rail TOC, so this is optional, but a visible top-of-file TOC helps offline readers.
• Consolidate emoji usage toward the documented five. Run a PR that replaces ad-hoc emojis (:zap:, :fire:, etc.) with the standard ones, or — alternatively — document the extended palette in CONTRIBUTING.md so future contributors know the rules.
• Annotate section introductions. A one-line "read this section when..." callout per section makes the list dramatically more usable without adding entries (see the User Guide for a worked example).
• Add a STYLE.md or extend CONTRIBUTING.md with concrete formatting rules (bullet style, sentence case vs title case for annotations, when to use nested bullets like the Platform Engineering section). Reduces back-and-forth on PRs.
• Protect master if more maintainers join. Require one approving review. Current single-maintainer model does not need it.
• Document the sponsorship banner in CONTRIBUTING.md so it is clear what the policy is for future banners.
• Remove obviously dead entries rather than waiting for user reports — a once-a-year sweep of the list against a link checker would eliminate most user-facing broken-link issues.

Note

The common thread in this list: improvements that make curation cheaper and more visible without turning the list into a database. Anything that adds a build step, a dependency, or a CI/CD pipeline deserves a very high bar.