Inside swiftlang/swift-book: the DocC source of The Swift Programming Language

What actually sits in the swiftlang/swift-book root

The repository holds the source of one book. The Swift Programming Language is sometimes abbreviated TSPL, its text is written in Markdown, and the built result is published on docs.swift.org through Swift-DocC instead of being shipped out of this repository. Anyone hunting for a library to depend on finds nothing to link against here. The deliverable is a documentation site, and the audience is split between people reading about Swift and people changing how Swift is described.

The root is short enough to read in one breath: eleven entries, made up of 4 dotfiles, 3 directories and 4 files. Beside README.md, CONTRIBUTING.md and Style.md sit `.gitattributes`, `.gitignore`, `.git-order-file` and `.git-blame-ignore-revs`, plus `.github/`. Two of those dotfiles are pure git plumbing rather than Swift content: one fixes the order in which files are listed, the other names revisions that blame should skip.

Nothing in that listing compiles. There is no package manifest and no dependency file here, so no toolchain or build system is versioned. The text, the writing rules and the DocC bundle are the entire project. The default branch is `main`, the repository is not archived, and it carries the Apache-2.0 licence with its last push recorded as 2026-09-29T18:28:03.000Z. For a reader that is background, but for a would-be contributor it means the code you touch is prose, and the only build step in the whole tree belongs to the external Swift-DocC project.

One DocC command renders the whole book locally

Cloning the project is step one, and it is also the whole setup. The documented build is a single invocation from the repository root:

docc preview TSPL.docc

DocC compiles the bundle, starts a local server and prints a link. Opening that link is step two, and it gives you the article tree a reader sees on docs.swift.org, rendered from your checkout rather than from the published build. The editing loop follows from that: change a Markdown file inside the bundle, let the preview rebuild, reload the browser and read the sentence in place with its surrounding paragraphs and navigation intact. For a book where a single rewording can affect headings, cross references and code listings, seeing the rendered result before opening a pull request is the reason to build locally at all.

There is no wrapper script to learn and no configuration file pointing DocC at a different output directory. The bundle name is the only argument you pass. Before reading anything, the worthwhile check is that your checkout actually contains the `TSPL.docc/` directory; a copy without it gives you a README, a style guide and nothing to preview.

Docc arrives from a toolchain or from Xcode

That command assumes DocC is already installed, and this project does not install it for you. Two routes are described, and each one changes what you type.

If you downloaded a toolchain from Swift.org, the binary sits in `usr/bin/` relative to that toolchain's installation path, and your shell `PATH` has to include that directory or the shell cannot resolve the command. If you installed through Xcode, the same preview runs through `xcrun`:

xcrun docc preview TSPL.docc

The difference matters more than it looks. The toolchain route fails at the shell, and the documented remedy is editing `PATH` so every later invocation resolves. The Xcode route hands lookup to whichever developer directory Xcode has selected, so the preview follows the selected Xcode rather than a directory you typed yourself. In both cases the arguments stay the same: the bundle name, run from the repository root. Keep that difference in mind when a contributor reports that the preview command works on their machine and fails on yours, since the two sides may simply be using different ways of finding the same binary.

Typos travel as pull requests, rewrites as pitches

Contribution has two speeds, and the split is drawn by size rather than by topic. Typo fixes and changes to a few paragraphs take the direct route: fork the repository and open a pull request. Anything larger is expected to start somewhere else entirely, as a pitch thread in the Swift forums at forums.swift.org/c/swift-documentation/92, so the approach and any problems surface before the writing effort is spent.

Here is the detail worth reading twice. One page states that a formal contribution process for the document is still in development, and the lines below it hand you a process anyway: fork, pull request, forum pitch for larger changes, the issues page for content bugs, and the Swift Code of Conduct for discussions. A root `CONTRIBUTING.md` is linked on top of that. The rules you follow are therefore split across a README paragraph and a root file, with nothing stating which one wins when they disagree, and no dated revision to appeal to. A change that is neither a typo nor a rewrite forces a judgement call before you write a line.

Content bugs go to the GitHub issues page rather than to the forums, which keeps defects in the wording separate from arguments about how the wording should read. Forks follow `main`, whose recorded last push is 2026-09-29, so a review comment can point at a specific recent state of a file.

Two style authorities decide every sentence

Prose changes are judged against 2 documents, and one of them lives outside the repository. Content follows the Apple Style Guide, published by Apple, plus the book's own style guide kept at `Style.md` in the root. The README reaches both through link definitions rather than inline text, and the local one is addressed as a root-relative path, so the same reference resolves whether the page is read on GitHub or rendered inside the documentation site.

In practice a sentence can fail review on grammar grounds without anyone arguing about Swift. The house rules sit beside the text they govern, which means edits and style rules can move in the same change, and a reviewer disagreement about phrasing has a written answer to point at instead of a preference to assert. Contributors who write for a living will already know how this works from other style guides; the difference here is that the book that teaches a language also publishes the house style its chapters are held to, and `.git-blame-ignore-revs` at the root is the file where a mechanical pass over the text gets listed so blame skips it.

The gap between a reader and a fork

Several things a newcomer will look for are not written down. No rollback procedure appears anywhere in the README, so a contributor who wants the previous state of a chapter has to dig through commits instead of restoring a tag. Nothing in the root listing points at a tutorial, an exercise set or a runnable sample package; the repository presents itself as the source for one book, and its reader-facing output is a single documentation site. The `bin/` directory appears at the root and is explained nowhere in the README, so nothing in the written instructions tells you what lives there.

The sharper limitation concerns who the workflow actually fits. The fork and pull request path assumes you have DocC installed and can preview the page you changed. The forum pitch path assumes your change is large enough to be worth discussing before it is written, which by definition excludes the case of a reader who found one wrong sentence in a published chapter. That person is pushed toward the issues page and then waits for someone with write access to pick it up. For the book's core audience, that is the right trade. For anyone planning a systematic pass over a single chapter, it is the part of the process to budget time around.

Reading the published site against building the source

Two ways of working with this project are both reasonable, and they differ in more than convenience. Reading docs.swift.org requires no checkout, no toolchain and no `PATH` edit, and it always shows the state the Swift project chose to publish. Building locally requires DocC from a toolchain or Xcode, a shell that can find it, and a clone containing the `TSPL.docc/` bundle. What local building buys is the ability to read your own edits in rendered form before anyone else sees them, which is why writers use it and why most readers never will.

The second choice is sharper, and it lives on the contribution side. A small correction is a pull request against the current `main` branch, reviewed against both style guides. A large restructuring is a forum conversation with no written specification to satisfy and no stated timeline for a decision. If your goal is to learn how the language is described, the published book is faster and carries no setup cost. If your goal is to fix or extend the description, the repository is the only place where the text can actually change, and which of the two routes you should take depends on how many chapters your edit touches.

Editorial conclusion

Read the published book on docs.swift.org if you only need the Swift language reference, because nothing in this repository compiles into a library you can depend on. Clone it when your intent is to change wording. Small corrections travel as pull requests, and anything larger is expected to start as a pitch thread in the Swift forums, since the README says the formal contribution process is still in development. Verify 2 things first: that `docc` resolves from your PATH, and that your change survives review against Style.md.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. swiftlang/swift-book on GitHub