Swift's language book moves its publication pipeline to DocC

A documentation repository becomes more useful when its contents generate the documentation people actually read. Swift's language book has now reached that point. The February 16 publication announcement says that The Swift Programming Language now uses DocC, starting with Swift 5.8, and is ready to accept content contributions under the Documentation Workgroup's direction.

The change completes a transition that began with opening the source. A public repository alone could not establish that an accepted edit would appear in the published book. The project first needed to replace its publication machinery, preserve the reading experience, and make the open tooling suitable for sustained narrative documentation.

I value Swift's explicit treatment of optional values and its approach to value semantics. Those ideas need explanations that remain precise as the language changes. A public path from a proposed correction to the published explanation makes the language easier to evaluate on its actual rules.

Why source availability came first

Kyle Murray's August 2022 announcement introduced the open-source book and asked contributors to build it locally with DocC. At that stage, the version published on Swift.org still came from Apple's internal toolchain. The initial work therefore concentrated on publication fixes, with only minor changes to the content.

That ordering was reasonable. Inviting broad revisions before the open repository could produce the published result would have left contributors working against an incomplete process. A correction might be accurate while still encountering a broken rendering path. Establishing the publication path first gave later editorial contributions a usable destination.

The August announcement made the intended transition explicit. Once the repository could generate a high-quality version, the project would publish directly from it and start accepting more substantial content changes. February's announcement records that transition, after more than 50 merged pull requests during the conversion.

This history also changes how the work should be described. February is the move to DocC publication and broader content contribution. It is not the first availability of the book's source. Treating those as separate milestones explains why months of work were necessary between opening a repository and inviting general revisions.

A book has different navigation needs

The February announcement identifies changes to DocC made during the conversion. Authors gained control over automatic see-also sections, and the reading experience gained new navigation within a page. These changes address the needs of long-form content, where the order of explanation carries part of the meaning.

A language chapter may introduce a concept and then refine it through examples and exceptions. Readers need to move within that explanation without losing its structure. Automatically generated related material also needs to fit the author's intended progression. The publication announcement does not claim that API references and books require identical organization.

Package authors can benefit from the same work. The announcement specifically points to documentation for large or complex packages as another use for improvements to linear narratives. A package with a conceptual introduction can explain its model before asking a reader to interpret individual declarations.

That is the part of this change I find most useful. Good documentation needs room to explain why a rule exists and how it interacts with surrounding rules. Generating a list of declarations cannot supply that explanation by itself, even when the reference material is complete.

Contribution scope still matters

The announcement points prospective authors to accepted Swift Evolution proposals and the book's issue tracker. Both offer concrete subjects for documentation work. A language feature needs an explanation of its accepted behavior, while an issue can identify a gap or an existing passage that readers find confusing.

Large changes should begin with discussion in the Swift Documentation forum, according to the contribution guidance linked by the announcement. That makes sense for a book whose chapters depend on shared terminology and the order in which concepts appear. A new section can be locally accurate and still repeat material or assume knowledge introduced later.

Small corrections have different costs. A typo or an unclear sentence usually needs less advance design than a new chapter. Opening the content workflow allows those changes to use the same public review process as larger work, while the workgroup remains responsible for the overall direction.

The relevant unit of review is therefore the explanation in context. A proposed sentence should fit the language behavior it describes and the surrounding teaching sequence. Publication through an open tool makes the result inspectable, but editorial review still determines whether the passage belongs.

Shared tooling for translations

Translation projects can now use the same publication pipeline as the English edition. The February announcement also describes how translators can follow English changes through forum pitches and GitHub pull requests. That gives them a visible record of both proposed structural changes and accepted edits.

Shared tooling does not make the translation work automatic. Terminology and examples still need attention in each language, and an English revision can require a corresponding editorial decision elsewhere. The benefit is that translators can spend more effort on that work without separately reproducing a private publication process.

The announcement identifies interactive content, offline content, and tested code listings as areas for further improvement. These are opportunities for contributors, not capabilities that the announcement says are finished. That distinction matters especially for examples, since publishing a code listing does not establish that the publication tool has compiled or executed it.

DocC publication gives the book a public implementation path for those improvements. A change to the prose, a change to the navigation, and a change to the documentation tool can now be discussed in their respective repositories while contributing to the same published reading experience.