The Artsy engineering handbook: one repository, ten sections, generated READMEs

Ten section directories, one generated table of contents

The repository is a documentation set, and its shape is visible in the directory listing. The top level holds `RFCs/`, `careers/`, `culture/`, `events/`, `hiring/`, `onboarding/`, `playbooks/`, `practices/`, `resources/` and `systems/`, plus `README.md`, `CONTRIBUTING.md`, `LICENSE.md`, `spellcheck.json`, `dangerfile.ts` and a `scripts/` directory.

The README itself is the entry point and carries a table of contents listing those sections with a one-line summary each: Requests for Comments for engineering-wide proposals that require discussion and feedback before implementation, Careers for growing people, Engineering Culture, Events for regularly occurring meetings, Hiring, Onboarding Notes for New Engineers, Playbooks for tips, procedures and best practices, Engineering Practices for cross-functional concerns, Engineering Recommendations for further reading, and Systems for how the systems work.

That table is not typed by hand. It sits between `<!-- start_toc -->` and `<!-- end_toc -->` marker comments wrapped in `prettier-ignore` comments, and `doctoc` appears in the development dependencies, so the table of contents is regenerated rather than maintained. The README also states that the repository is a work in progress and that the first pull request of a new team member could be to fix or add to it, which is an honest description of a handbook that has to survive staff turnover.

The sections are not equally accessible from outside. The Notion pages for team organisation and the Slack channels for the practices are marked as private, so a reader outside Artsy gets the writing but not the links behind it.

The section READMEs and the tech radar are generated by scripts

The repository does something unusual for a handbook: part of it is written by code. Two scripts run before every commit, and both are declared in the `scripts` block of `package.json`.

"scripts": {
  "precommit": "yarn setup-structure && yarn sort-tech-radar-data && lint-staged",
  "prepush": "echo 'skipping yarn danger local'",
  "setup-structure": "ts-node --skip-project scripts/create-readmes.ts && git add .",
  "sort-tech-radar-data": "ts-node scripts/sort-tech-radar-data.ts && git add ."
}

`setup-structure` runs `scripts/create-readmes.ts` with `ts-node --skip-project` and then stages the result, and `sort-tech-radar-data` runs `scripts/sort-tech-radar-data.ts` and stages that too. The two `git add .` calls are the important detail: both scripts write files into the working tree and stage them as part of the same commit, so the generated section READMEs and the sorted tech radar data land in a commit as ordinary changes rather than as a separate build artefact.

The `prepush` script is a one-liner that echoes `skipping yarn danger local`, which means the Danger check that normally reviews pull requests is not run locally before a push. The hook itself is provided by husky, and the `precommit` chain is what a contributor actually feels on every commit.

prettier, lint-staged and Danger decide what a pull request looks like

The formatting configuration is explicit, and it is the clearest statement of the repository's editorial rules. The `prettier` block sets `printWidth` to 115, turns semicolons off, keeps double quotes, keeps bracket spacing, and sets `proseWrap` to `never`, which is the setting that stops the formatter from rewrapping prose and reflowing sentences you wrote on purpose.

"prettier": {
  "printWidth": 115,
  "semi": false,
  "singleQuote": false,
  "bracketSpacing": true,
  "proseWrap": "never"
}

`lint-staged` is wired to the file types the repository actually contains, which is ts, json and md:

"lint-staged": {
  "*.{ts,json,md}": [
    "yarn prettier --write",
    "git add"
  ]
}

Two things follow from that. A Markdown file that goes through prettier with `proseWrap: never` keeps its line breaks, so a documentation pull request is not a reformatting exercise. And because markdown is in the lint-staged pattern, prose in the handbook is subject to the same toolchain as the TypeScript, which is a deliberate way of treating a handbook as code.

Pull request review is handled by Danger, through `dangerfile.ts` at the repository root, and the CI badge points at CircleCI. The `spellcheck.json` file at the root is a separate gate for spelling. The versions pinned for all of this are old: `danger` at `^7.0.9`, `husky` at `^0.14.3`, `lint-staged` at `^7.2.2`, `prettier` at `^1.16.4`, `typescript` at `^3.0.1` and `ts-node` at `^7.0.1`.

Cross-functional teams and three engineering practices

The organisational content is specific rather than aspirational. Teams at Artsy are cross functional, and a regular team is described as a Product Manager, a Product Designer, a Data Analyst, an Engineering Manager and Engineers. Each team has a mission, and the README gives a sample one, from Emerald, about facilitating an enjoyable, consistent, secure and global deal-closure experience. Teams also carry quarterly goals aligned with company objectives.

Engineers are encouraged to join a practice in addition to their product team, and three are named with their leads: Platform Practice with Matt Jones, Mobile Practice co-led by George Kartalis and Sultan Al-Maari, and Web Practice with Rachel Quartararo. Each practice has its own Slack channel and its own Notion page, both of which are marked private in the README.

The link between the documentation and the working week is the support section, which says that if you are on call or asked to fix an immediate issue, reference the engineering playbooks for up-to-date solutions to potential issues. That link between the handbook and the incident response is the operational argument for keeping the handbook in the repository rather than in a wiki: the playbooks are versioned, reviewed and change-controlled, and the page a person opens at 3am is the same page that went through a pull request.

RFCs for decisions, playbooks for incidents, onboarding for week one

Three sections carry most of the day to day value, and they cover different moments in an engineer's life.

The RFC section is for engineering-wide proposals that require discussion and feedback before implementation. It is the mechanism that makes a decision durable: a proposal is written down, argued over, and the outcome stays in the repository as a record of what was agreed and why. The onboarding section covers the first steps to being productive and is where a new team member is pointed on arrival, along with an external reading on the first 60 days at an engineering job.

The playbooks section holds tips, procedures and best practices, and it is also what the on-call flow points to. The practices section handles cross-functional concerns, the systems section describes how the systems work, and the resources section collects further reading. Events, hiring and careers complete the set, with documentation on regularly occurring events and meetings and on how the company hires and grows people.

What is missing is as notable as what is there. There is no repository of runnable code, no library to install and no public API surface. The `TypeScript` in this project is repository maintenance: the dangerfile, the two generation scripts, and the `tsconfig.json` that configures them. The application itself lives elsewhere, and the README links to the public API documentation and the engineering blog as the outside doors into it.

A public repository that leans on private Notion pages and Slack

The limitations of the model are structural, and they show up in the links.

Everything that is actually operational sits behind a lock. The team organisation is a Notion page, the three practices are Notion pages with private Slack channels, the engineering playbooks used for on-call are a Notion page, and the dev Slack channel is marked private. The public repository therefore holds the writing, the rationale and the process, while the live state lives in a hosted workspace that a reader cannot open. A team that copies the structure inherits the split, and has to decide which half of its documentation is allowed to be public.

The tooling is the second limitation, and it is a matter of age. The development dependencies pin `typescript` at `^3.0.1`, `ts-node` at `^7.0.1` and `prettier` at `^1.16.4`, with `husky` at `^0.14.3` and `danger` at `^7.0.9`. These are the versions the repository was built against; a team that wants the same structure on a current Node release has to do that upgrade itself, and the risk sits in the hooks, since a broken precommit chain either blocks every commit or gets disabled by habit.

The third limitation is that a handbook is only as good as its review. The README itself admits the repository is a work in progress and invites a first pull request to fix it, which means the quality of any given page depends on whether a colleague happened to read it.

There is a clear alternative approach, and the repository shows both halves of it. A hosted workspace with its own permissions, sharing and versioning handles private material without a public repository, and it is what Artsy uses for the Notion half. The git half adds what a workspace cannot easily add: pull request review, a change log, and a diff that shows who decided what. The choice is not either or, and this repository is the argument that the two halves complement each other rather than replace each other.

CC-BY-4.0 for the text, and a last push on 2026-10-12

The licence is Creative Commons Attribution 4.0, which is recorded in the `LICENSE.md` file, in the `license` field of `package.json`, and in the badge in the README pointing at the Creative Commons deed. That is an unusual choice for a repository containing TypeScript, and it follows from the nature of the content: the handbook is prose meant to be read, adapted and attributed, which is what a Creative Commons licence is for.

The repository is not archived, and the last push was on 2026-10-12. There are no GitHub releases, which fits a repository whose unit of change is a pull request against a document rather than a shipped artefact. The default branch is `main`, CI is CircleCI, and the supporting files are the ones you would expect from a repository that treats itself as a project: `CONTRIBUTING.md`, `.github/`, `.circleci/`, `.vscode/`, `.gitignore` and a `package-lock.json` beside the `package.json`.

Because there are no releases, the upgrade story is entirely in the dependency pins and in the generation scripts. A team that forks this structure inherits that responsibility directly, with no upstream tag to point at.

Editorial conclusion

This repository is worth reading and copying as a template if you are building an engineering handbook that has to be reviewed in pull requests, because the structure, the RFC process and the playbooks are concrete and the generation scripts keep the navigation from rotting. It is not a template for a company whose documentation lives in a hosted wiki, and it is not a source of runnable code: the TypeScript in it is repository maintenance, not a product. Before adopting the pattern, check whether your organisation can accept pull request review as the only way to change a page, confirm that the Notion-hosted material that Artsy links to can stay private while the repository stays public, and read `package.json` carefully, because the toolchain pins are several years old and will need updating before they work on a current Node release.

Frequently asked questions

Official sources

1. artsy/README on GitHub
2. Issues
3. License: CC-BY-4.0
4. README