Swift separates documentation architecture from its website redesign
Two Website Workgroup projects address where Swift information belongs and how the site presents it. Package Manager documentation shows why those are separate problems.
Swift Package Manager has documentation in several places, each plausible enough to look authoritative. A user can find a tutorial, repository markdown or an API reference without knowing how the pieces relate. Changing colors and navigation labels cannot by itself resolve that ambiguity. The Swift Website Workgroup has opened a separate information architecture project alongside its website redesign to address the underlying organization.
The November 6 announcement identifies both efforts as open community projects. One covers information across Swift.org and the swiftlang GitHub organization. The other addresses the website's presentation and usability. Both are starting substantial work over the coming months, so the announcement describes a process rather than a completed new site.
I find the distinction useful when evaluating a language ecosystem. A well-designed language still needs documentation that explains which instructions apply and where to continue. Difficulty locating the right build instructions adds to the friction of working with a toolchain before any source code changes.
A single topic can have several plausible homes
The information architecture brief uses Package Manager documentation as a case study. It identifies material on Swift.org, markdown in the package manager repository, generated PackageDescription documentation and Apple developer documentation. These have different forms and audiences, but a visitor looking for help with packages can encounter all of them.
The brief does not argue that every page must become one enormous document. Its principle is a single source of truth for a topic across official Swift sites. A tutorial and an API reference can serve different purposes while making clear which information each owns. The maintenance problem arises when overlapping accounts evolve independently and leave readers unsure which one is current.
The project also acknowledges sites outside its direct control, including developer.apple.com and Swift Package Index. An information architecture cannot simply relocate all external documentation by declaration. It needs a rationale for what belongs on each site and how readers reach related material.
Another case study concerns the path from Swift.org's contribution entry point to the getting-started instructions for the compiler repository. The brief describes a tangle of links and backlinks with only one path reaching the useful instructions. That is a navigation failure with a concrete destination, rather than a general complaint that the website needs to look newer.
Audience determines the explanation
The architecture brief distinguishes newcomers, existing Swift developers and contributors. It asks each page to have a primary audience even when the content also helps other readers. That affects the assumptions a page can make about what its visitor already knows.
For example, the brief identifies GitHub as a suitable home for contribution details, while Swift.org can address newcomers and language users. This separates the question of where content is maintained from whether a visitor should have to understand the repository layout to find it.
Progressive disclosure is another proposed principle. A high-level account should lead to increasing detail. The visitor can first establish whether the topic is relevant, then follow the path into the specific API or contribution instructions. That reduces the demand for one page to explain every detail to every audience at once.
The project also identifies use cases beyond Apple application development, including server software and embedded work. These audiences can require different entry points even when they share the same language. A microcontroller example and a server deployment guide do not become interchangeable because both use Swift.
The redesign has its own implementation scope
The redesign brief explicitly says completion of the information architecture is not a prerequisite. Its work includes layout, navigation and reusable design components. That allows presentation work to proceed while the wider content organization receives its own review.
The redesign continues using Jekyll and Sass. It calls for portable styling and reusable components that can support later site implementation changes. The immediate proposal therefore does not require replacing the site's technology stack before improving its presentation.
Reusable components matter because maintenance continues after the first redesigned page. A shared navigation or content component gives later changes a consistent implementation point. The brief also includes accessibility and cross-browser work in the implementation scope, which makes usability broader than the appearance of a desktop screenshot.
Contributors can work on different problems
The architecture project plans to establish principles, apply them to existing content and then implement the resulting organization. It promises architecture documents in the forums for review. That gives contributors a place to challenge the content model before individual pages are rearranged.
The redesign supplies a parallel route for work on the interface and its components. A contributor can evaluate whether a layout helps readers reach a destination, while another examines whether the destination is the right authoritative page for the subject. These questions interact without requiring identical expertise.
My preference is for documentation whose maintenance boundaries are visible. Swift's language design deserves explanations that distinguish learning material from exact reference information. These projects identify that responsibility explicitly, with Package Manager documentation and contribution navigation providing concrete places to apply the proposed principles.