Wanted to share a quick update on where things are with the Docs, and what's cooking in that respect today. The original inception for the docs repository stemmed from the somewhat aggregated collection of articles on Swift.org, so preparing and tracking all of that, migrating the content, and getting it published within the project's infrastructure is where we're at.
I've expanded on the original docs proposal to create a more detailed plan that looks at all of the various existing articles, breaks down where we'll organize them into DocC catalogs, and prepares for that work. In order to keep that all visible to the community, I've opened quite a pile of issues under the Docs repository with the label content migration. The idea being to make sure it's all captured and we don't drop anything through the cracks.
Every document is getting explicit review, and part of this process is identifying the relevant reviews, including the original authors in many cases, and leaning on steering groups more generally to help provide reviewing more generally, and for any new content. I've started reaching out to the steering and workgroups to begin touching on some of this work. One of the recent suggestions was to migrate first, not adjusting anything, and then tracking updates with pull requests or additional commits to make it clear what's getting changed and updated, so that's the general process I'll be using for most of this. A few will fall outside this, due to earlier conversations and planning, but most will focus on migrate first, then update.
Migration Summary
| Source path | GitHub issue | Proposed reviewer | Target catalog |
|---|---|---|---|
documentation/index.md |
#37 | Website WorkGroup | — |
documentation/concurrency/index.md |
— | — | — (already redirected) |
documentation/package-manager/index.md |
— | — | — (already redirected) |
documentation/api-design-guidelines/index.md |
#44 | @swiftlang/language-steering-group |
api-guidelines/APIGuidelines.docc |
documentation/articles/value-and-reference-types.md |
#45 | @swiftlang/language-steering-group |
language-guides/LanguageGuides.docc |
documentation/articles/wrapping-c-cpp-library-in-swift.md |
#46 | @swiftlang/language-steering-group |
language-guides/LanguageGuides.docc |
documentation/cxx-interop/index.md |
#49 | @swiftlang/language-steering-group |
TBD (interop team) |
documentation/cxx-interop/project-build-setup/index.md |
#50 | @swiftlang/language-steering-group |
TBD (interop team) |
documentation/cxx-interop/safe-interop/index.md |
#51 | @swiftlang/language-steering-group |
TBD (interop team) |
documentation/cxx-interop/status/index.md |
#52 | @swiftlang/language-steering-group |
TBD (interop team) |
documentation/lldb/index.md |
#53 | @swiftlang/language-steering-group |
TBD |
documentation/tspl/index.md |
#43 | @swiftlang/language-steering-group |
Redirect to swift-book |
documentation/standard-library/index.md |
#54 | @swiftlang/language-steering-group |
Redirect to stdlib catalog (pending) |
documentation/swift-compiler/index.md |
#55 | @swiftlang/language-steering-group |
TBD |
documentation/core-libraries/index.md |
#48 | Each library's own team | Redirect to library docs |
documentation/source-code/index.md |
#38 | Swift Core Team | — |
documentation/source-compatibility/index.md |
#39 | Swift Core Team | — |
documentation/continuous-integration/index.md |
#40 | Swift Core Team | — |
documentation/monthly-non-darwin-release/index.md |
#41 | Swift Core Team | — |
documentation/server/index.md |
#42 | @swiftlang/server-workgroup |
Redirect to get-started/cloud-services |
documentation/server/guides/index.md |
#47 | @swiftlang/server-workgroup |
server-guides/ServerGuides.docc |
documentation/server/guides/building.md |
#19 | @swiftlang/server-workgroup |
server-guides/ServerGuides.docc |
documentation/server/guides/testing.md |
#18 | @swiftlang/server-workgroup |
server-guides/ServerGuides.docc |
documentation/server/guides/memory-leaks-and-usage.md |
#20 | @swiftlang/server-workgroup |
server-guides/ServerGuides.docc |
documentation/server/guides/allocations.md |
#20 | @swiftlang/server-workgroup |
server-guides/ServerGuides.docc |
documentation/server/guides/linux-perf.md |
#20 | @swiftlang/server-workgroup |
server-guides/ServerGuides.docc |
documentation/server/guides/performance.md |
#20 | @swiftlang/server-workgroup |
server-guides/ServerGuides.docc |
documentation/server/guides/llvm-sanitizers.md |
#16 | @swiftlang/server-workgroup |
server-guides/ServerGuides.docc |
documentation/server/guides/packaging.md |
#17 | @swiftlang/server-workgroup |
server-guides/ServerGuides.docc |
documentation/server/guides/deployment.md |
#6 | @swiftlang/server-workgroup |
server-guides/ServerGuides.docc |
documentation/server/guides/deploying/ubuntu.md |
#56 | @swiftlang/server-workgroup |
server-guides/ServerGuides.docc |
documentation/server/guides/deploying/digital-ocean.md |
#57 | @swiftlang/server-workgroup |
server-guides/ServerGuides.docc |
documentation/server/guides/deploying/aws.md |
#58 | @swiftlang/server-workgroup |
server-guides/ServerGuides.docc or deprecate |
documentation/server/guides/deploying/aws-copilot-fargate-vapor-mongo.md |
#59 | @swiftlang/server-workgroup |
server-guides/ServerGuides.docc |
documentation/server/guides/deploying/aws-sam-lambda.md |
#60 | @swiftlang/server-workgroup |
server-guides/ServerGuides.docc |
documentation/server/guides/deploying/gcp.md |
#61 | @swiftlang/server-workgroup |
server-guides/ServerGuides.docc |
documentation/server/guides/deploying/heroku.md |
#62 | @swiftlang/server-workgroup |
server-guides/ServerGuides.docc or deprecate |
documentation/server/guides/libraries/concurrency-adoption-guidelines.md |
#63 | @swiftlang/server-workgroup |
Redirect to Swift Migration Guide |
documentation/server/guides/libraries/log-levels.md |
#64 | @swiftlang/server-workgroup |
Redirect to swift-log docs |
documentation/server/guides/passkeys.md |
#65 | @swiftlang/server-workgroup |
server-guides/ServerGuides.docc |
documentation/articles/getting-started-with-vscode-swift.md |
#66 | @swiftlang/ecosystem-steering-group |
ecosystem-tools/EcosystemTools.docc |
documentation/articles/zero-to-swift-emacs.md |
#67 | @swiftlang/ecosystem-steering-group |
ecosystem-tools/EcosystemTools.docc |
documentation/articles/zero-to-swift-nvim.md |
#68 | @swiftlang/ecosystem-steering-group |
ecosystem-tools/EcosystemTools.docc |
documentation/articles/wasm-getting-started.md |
#69 | @swiftlang/ecosystem-steering-group |
ecosystem-tools/EcosystemTools.docc |
documentation/articles/static-linux-getting-started.md |
#70 | @swiftlang/platform-steering-group |
platform-guides/PlatformGuides.docc (new) |
documentation/articles/swift-sdk-for-android-getting-started.md |
#32 | @swiftlang/platform-steering-group |
platform-guides/PlatformGuides.docc (new) |
Versioning Swift Docs
Another big step in this is bundling together the documentation where it makes sense and starting to provide combined, bundled and hosted DocC archives aligned to Swift toolchain releases. There are several moving parts here, including assembling the script and metadata to collect all the existing content, folding in the work that's ongoing to include the standard library in the docs, assembling an appropriate URL scheme for referencing the content, and working with the Website Workgroup and our design teams to align navigation within these published archives with the content at Swift.org.
Today we're already publishing 8-9 archives to either swift.org or docs.swift.org, the detail of which is included in set up archive publishing · Issue #24 · swiftlang/docs · GitHub. A few of these content collections aren't aligned with a Swift release - they're versioned independently (VSCode for Swift extension and Swiftly), but most are. So soon up is prototyping combining these catalogs together into a single combined archive that we can publish under a URL structure that supports versioned content as we step forward. I did an initial prototype before Thanksgiving last year, and it looked like we could get to published content with URI's along the lines of:
https://docs.swift.org/6.3/documentation/the-swift-programming-language/https://docs.swift.org/6.3/documentation/migrationguide/https://docs.swift.org/6.3/documentation/docc/https://docs.swift.org/6.3/documentation/packagemanagerdocs/https://docs.swift.org/6.3/compiler/documentation/diagnostics/
And arrange it so that if you leave off that 6.3 (the Swift toolchain version) we'll put in the relevant redirects to send you to the latest release, allowing for specifically versioned content but also reasonably stable redirect URIs that you can use to link into content.
There's additional work to tie this into theme'd presentations for the DocC content to align the visuals so that it doesn't feel discordant from the swift.org website, which follows on from how we work to structure and publish this content. But before we get there, we need to nail down the how the archives are getting combined and published.
So the next steps are running two things in parallel:
- Starting to migrate some of the articles from swift.org in order to get enough content in the DocC catalogs so they aren't anemic - I feel it's awkward to have a published catalog with only a single article or two in it, and I'm trying to avoid that.
- Reworking the prototyping to assemble and merge all the catalogs, including existing ones across the
swiftlangrepositories, to identify and work out any issues, and get something up to get content published. This includes where and how we pull from branches vs. the current pattern of grabbing frommainfor a lot of content, and generally starting to support versioned content for DocC using the pattern that Swift Package Index set up and has been running so successfully.
In a week or two, when I've had enough time to migrate a few articles and redo the prototyping for the combined content, I'll set up an office-hours call for anyone interested to join, ask questions, get involved, etc. For a lot of this process, I'm trying something with a plan to iterate and evolve the process as we learn what works and what doesn't, and broaden our ability to get great docs for Swift hosted through swift.org.
In the meantime, if you have questions, feel free to reach out to me here (through the forums) and I'll try and answer and keep you all informed and involved in the process.