Hi All!
I want to follow up on the proposal for a central documentation repository. We now have a central docs repository for swiftlang! 
At the moment, it is bare bones, and we'll be building it in public, following the details of that proposal. I'll be tracking and coordinating work on the content with issues on that repo, with a starting point of getting the structure set up, CI operational, building and checking the content collections, and then getting work done to migrate some of the content that's stashed (kinda buried in some places) as articles on www.swift.org into this new structure, preserving URLs with redirects as it comes online.
The repository is (going to be) a collection of DocC catalogs - taking advantage of the DocC tooling this project supports - wrapped in very light Swift packages in order to enable Snippets support to validate code snippets. The first few catalogs are stubbed out, without any content, in a pull request adding the basic structure, up now.
At a high level, all content will have reviewers - and the people to help review are going to be delegated from the various steering groups as it aligns with the content collections (language, ecosystem, and platform). The reviewers are coordinated with the repositories' CODEOWNERS file, which is starting out with the GitHub teams that align with those collections.
When I first proposed this structure, it was from looking at the collection of articles that had grown organically within the website. Quite a few of them having fantastic content, but not always easily findable. One of the major goals for this effort, alongside the work of the Information Architecture project under the Website workgroup, is to make all of our content more findable, browsable, and easier to access. One of the other major goals is to enable versioned documentation content for the collections that match quite directly to the Swift toolchain releases, taking inspiration from the great folks who run Swift Package Index and hosting the documentation for thousands of Swift packages.
I've talked with a few community members over the past several months who are interested in contributing to content, and will continue as we go forward, as well as doing some writing myself. More on that in follow-up threads, but if you're interested in helping to contribute please let me know. I expect we'll iterate on the process for creating and reviewing content as a community.
First things first, we need to get the structure in place, lay down how we're publishing this as static content, and get all the pieces we'll build on top of set up and operating, in order to start to update and/or migrate existing content, or create new content to fill in the gaps and share our knowledge.
I'll also mention that this repository is not, and will not be, the only source for documentation content for the Swift project. There are a number of places where DocC catalogs are sourced from and published to www.swift.org and docs.swift.org. Some of those we might want to migrate down the road, others I'm quite sure will be better off as their own repositories. Regardless, I'm going to work to wrangle as much of the publishing processes for sources of content from this new repository - so it should be where you can find out where any of the sources exist for content published to a static site at docs.swift.org, and linked from www.swift.org.
The list of content collections:
- The Swift Programming Language
- URL:
https://docs.swift.org/swift-book/documentation/the-swift-programming-language/
- URL:
- Swift Migration Guide
- URL:
https://www.swift.org/migration/documentation/migrationguide/
- URL:
- DocC documentation
- URL:
https://www.swift.org/documentation/docc/
- URL:
- Swift Package Manager Docs
- URL:
https://docs.swift.org/swiftpm/documentation/packagemanagerdocs/
- URL:
- Swiftly
- URL:
https://www.swift.org/swiftly/documentation/swiftly/install-toolchains/
- URL:
- VSCode for Swift extension
- URL:
https://docs.swift.org/vscode/documentation/userdocs/
- URL:
- Swift Compiler Diagnostics
- URL:
https://docs.swift.org/compiler/documentation/diagnostics/
- URL:
- Embedded Swift
- URL:
https://docs.swift.org/embedded/documentation/embedded/
- URL:
- Getting Started with Swift Server (tutorial-only DocC Archive)
- URL:
https://docs.swift.org/getting-started-swift-server/tutorials/getting-started-swift-server/
- URL:
There's a lot to work to get on with, and to avoid overloading a single thread in the forums, I'll be creating new threads for feedback and discussion, tagging them with documentation, and linking from relevant GitHub issues on the repository. I'm in the process of getting that set up now, to share implementation plans, get feedback, and align this all with the community.
