consolidating to a smaller opt-in initial set

Author: heckj

_data/authors.yml

@@ -551,3 +551,10 @@ mitchellallison:
   email: [email protected]
   github: mitchellallison
   about: "Mitchell Allison works on Distributed Systems in Swift at Apple."
+
+heckj:
+  name: Joe Heck
+  email: [email protected]
+  github: heckj
+  gravatar: 34fa393a8013e04c03deff379ac0a6f3ea7a23c5861a6f7410b409974218f5d2
+  about: "Joe Heck works on Swift as part of the Open Source Program Office at Apple."

_info-architecture/0003-swift-docs-proposal.md

@@ -172,65 +172,40 @@ Markdown files prefixed with `_` are typically only included in other files and
 ## Migration Plan
 
 This proposal is primarily meant to provide a guide to the structure for content as we want to see it.
-In the process of establishing this new repository and structure of DocC catalogs, the following files from swift.org are intended to be migrated.
-A full audit of the documentation for recency and relevancy is worthwhile, but beyond the scope of this proposal.
+In the process of establishing this new repository and structure of DocC catalogs, the following initial files from swift.org will be updated (if needed) and migrated, to establish the initial structure.
 
-This list is intended to be a guide, with additional potential updates from the relevant reviewing team, and is not expected to be complete in a single sweep.
-The migration can, and should, occur incrementally, building into the docs repository as supported by the community including content reviewers and their availability.
-The migration process itself will be tracked by pull requests and within an issue or issues housed at https://github.com/swiftlang/swift-org-website/, with the issues and tracking to be started if the proposal is approved.
-
-Files under the `documentation` directory on Swift.org:
+Files to migrate under the `documentation` directory on Swift.org:
 
 | `source` | status & destination |
 | - | - | 
 | [`api-design-guidelines/index.md`](https://www.swift.org/documentation/api-design-guidelines/) | translate to docc, break into multiple articles in `api-guidelines/APIGuidelines.docc` |
 | [`server/index.md`](https://www.swift.org/documentation/server/index.html) | deprecate & redirect to https://www.swift.org/get-started/cloud-services/ |
 | [`server/guides/index.md`](https://www.swift.org/documentation/server/guides/index.html) | translate, migrate to top level of `server-guides/ServerGuides.docc` |
 | [`server/guides/building.md`](https://www.swift.org/documentation/server/guides/building.html) | refine/update to provide examples of building, add section for debug vs. release and swift tooling, link to SwiftPM docs on building, add section about building in Linux using containers, add section on building with devContainers, add detail on static linux SDK, break out some content to a CI related article |
-| [`server/guides/testing.md`](https://www.swift.org/documentation/server/guides/testing.html) | heavily outdated - update to swift 6, swift-testing, break out some content into a "CI" focused article - focus on unit testing, leave room for functional, integration testing as sep articles |
-| [`server/guides/memory-leaks-and-usage.md`](https://www.swift.org/documentation/server/guides/memory-leaks-and-usage.html) | migrate as is - verify guides still work. Consider breaking into multiple smaller articles. |
-| [`server/guides/allocations.md`](https://www.swift.org/documentation/server/guides/allocations.html) | migrate as is, add reference to package-benchmark to help measure allocations, verify content is still current with subject matter experts |
-| [`server/guides/linux-perf.md`](https://www.swift.org/documentation/server/guides/linux-perf.html) |  migrate as is, update examples to use container and latest versions, break out a separate flame-graph article, verify content is still current with subject matter experts |
-| [`server/guides/performance.md`](https://www.swift.org/documentation/server/guides/performance.html) | revise to guidepints for understand performance, reference swift-performance-profiler, package-benchmark, break out flamegraph (what they are, how to read) into it's own article - include perf profiler flamegraphs tool references |
-| [`server/guides/llvm-sanitizers.md`](https://www.swift.org/documentation/server/guides/llvm-sanitizers.html) | merge content into 'build' and 'test' articles, deprecate/remove |
-| [`server/guides/packaging.md`](https://www.swift.org/documentation/server/guides/packaging.html) | add new overview of options, incl static-binary, container. reference runtime dependencies with static compilation options, example of docker w/ 2-stage build and using published docker binaries, break out distroless into it's own article |
-| [`server/guides/passkeys.md`](https://www.swift.org/documentation/server/guides/passkeys.html) | migrate content into article within https://github.com/swift-server/webauthn-swift.git |
-| [`server/guides/libraries/log-levels.md`](https://www.swift.org/documentation/server/guides/libraries/log-levels.html) | migrate content into swift-log (https://github.com/apple/swift-log/pull/370) |
-| [`server/guides/libraries/concurrency-adoption-guidelines.md`](https://www.swift.org/documentation/server/guides/libraries/concurrency-adoption-guidelines.html) | deprecate and redirect to https://www.swift.org/migration/documentation/swift-6-concurrency-migration-guide/enabledataracesafety (https://github.com/swiftlang/swift-org-website/pull/1186) |
-| [`server/guides/deployment.md`](https://www.swift.org/documentation/server/guides/deployment.html) | migrate as is - guide to deploying, revise as guidepost article |
-| [`server/guides/deploying/aws-sam-lambda.md`](https://www.swift.org/documentation/server/guides/deploying/aws-sam-lambda.html) | migrate as is - slightly outdated |
-| [`server/guides/deploying/aws-copilot-fargate-vapor-mongo.md`](https://www.swift.org/documentation/server/guides/deploying/aws-copilot-fargate-vapor-mongo.html) | migrate as is - slightly outdated |
-| [`server/guides/deploying/aws.md`](https://www.swift.org/documentation/server/guides/deploying/aws.html) | migrate as is - slightly outdated |
-| [`server/guides/deploying/digital-ocean.md`](https://www.swift.org/documentation/server/guides/deploying/digital-ocean.html) | migrate as is - slightly outdated |
-| [`server/guides/deploying/ubuntu.md`](https://www.swift.org/documentation/server/guides/deploying/ubuntu.html) | migrate as is - slightly outdated |
-| [`server/guides/deploying/heroku.md`](https://www.swift.org/documentation/server/guides/deploying/heroku.html) |  migrate as is - slightly outdated|
-| [`server/guides/deploying/gcp.md`](https://www.swift.org/documentation/server/guides/deploying/gcp.html) | migrate as is - slightly outdated |
+| [`server/guides/testing.md`](https://www.swift.org/documentation/server/guides/testing.html) | quite dated - update to swift 6, swift-testing, break out some content into a "CI" focused article - focus on unit testing, leave room for functional, integration testing as sep articles |
 | [`articles/static-linux-getting-started.md`](https://www.swift.org/documentation/articles/static-linux-getting-started.html) | migrate as is  - consider renaming or breaking into multiple, smaller focused articles, review any changes with previous authors (Alastair, Melissa) |
-| `migration-guide-swift3/_migration-guide.md` | migrate into https://github.com/swiftlang/swift-migration-guide |
-| `migration-guide-swift3/se-0107-migrate.md` | migrate into https://github.com/swiftlang/swift-migration-guide |
-| [`migration-guide-swift3/index.md`](https://www.swift.org/migration-guide-swift3/index.html) | migrate into https://github.com/swiftlang/swift-migration-guide |
-| `migration-guide-swift4/_migration-guide.md` | migrate into https://github.com/swiftlang/swift-migration-guide |
-| [`migration-guide-swift4/index.md`](https://www.swift.org/migration-guide-swift4/index.html) | migrate into https://github.com/swiftlang/swift-migration-guide |
-| `migration-guide-swift4.2/_migration-guide.md` | migrate into https://github.com/swiftlang/swift-migration-guide |
-| [`migration-guide-swift4.2/index.md`](https://www.swift.org/migration-guide-swift4.2/index.html) | migrate into https://github.com/swiftlang/swift-migration-guide |
-| `migration-guide-swift5/_migration-guide.md` | migrate into https://github.com/swiftlang/swift-migration-guide |
-| [`migration-guide-swift5/index.md`](https://www.swift.org/migration-guide-swift5/index.html) | migrate into https://github.com/swiftlang/swift-migration-guide |
 | [`concurrency/index.md`](https://www.swift.org/documentation/concurrency/index.html) | redirect to content at https://www.swift.org/migration/documentation/|  |swift-6-concurrency-migration-guide/enabledataracesafety |
 | [`articles/zero-to-swift-nvim.md`](https://www.swift.org/documentation/articles/zero-to-swift-nvim.html) | migrate into `ecosystem/EcosystemTools.docc` |
 | [`articles/zero-to-swift-emacs.md`](https://www.swift.org/documentation/articles/zero-to-swift-emacs.html) | migrate into `ecosystem/EcosystemTools.docc` |
 | [`articles/getting-started-with-vscode-swift.md`](https://www.swift.org/documentation/articles/getting-started-with-vscode-swift.html) | migrate into `ecosystem/EcosystemTools.docc` |
 | [`articles/wasm-getting-started.md`](https://www.swift.org/documentation/articles/wasm-getting-started.html) | translate and migrate into `ecosystem/WASM.docc` |
-| [`continuous-integration/index.md`](https://www.swift.org/documentation/continuous-integration/index.html) | migrate content to [project-operations](https://github.com/swiftlang/project-operations) repository |
-| [`source-compatibility/index.md`](https://www.swift.org/documentation/source-compatibility/index.html) | migrate to [project-operations](https://github.com/swiftlang/project-operations) repository (referencess to swift source compatibility project) |
-| [`source-code/index.md`](https://www.swift.org/documentation/source-code/index.html) | migrate to [project-operations](https://github.com/swiftlang/project-operations) repository (partial list to existing source code that goes into toolchain, needs updating if kept) |
+
+The Swift.org [documentation page](https://www.swift.org/documentation/) will be updated to point to these new DocC catalogs as the content migrates, to provide a way to navigate to the relevant content from swift.org.
+The navigability between DocC collections and integration of those collections into the broader design constraints for swift.org are being dealt with separately, as part of the Swift.org redesign efforts, and beyond the immediate scope of this proposal.
+
+As mentioned above, the metadata for the earlier pages will remain on Swift.org for some time, with the stubs of those articles being updated to provide HTML redirects for legacy URLs to the new location once the updated content is published using the DocC catalog.
 
 ### Swift.org documentation remaining and untouched:
 
+A full migration needs to be coordinated with relevant workgroups, and proceed incrementally as the availability of the community and relevant workgroups allow. 
+The migration process itself will be tracked by pull requests and within an issue or issues housed at https://github.com/swiftlang/swift-org-website/, and potentially moved to a new docs repository.
+
 - documentation/cxx-interop/index.md (Doug Gregor indicated a desire to reset and migrate this content into the Swift repository in the future)
 - documentation/cxx-interop/safe-interop/index.md
 - documentation/cxx-interop/project-build-setup/index.md
 - documentation/cxx-interop/status/index.md
 - documentation/articles/wrapping-c-cpp-library-in-swift.md
+- documentation/continuous-integration/index.md
 - documentation/core-libraries/index.md
   - documentation/core-libraries/_foundation.md
   - documentation/core-libraries/_libdispatch.md
@@ -241,6 +216,36 @@ Files under the `documentation` directory on Swift.org:
 - documentation/tspl/index.md
 - documentation/lldb/index.md
   - documentation/lldb/_playground-support.md
+- documentation/migration-guide-swift3/index.md
+  - documentation/migration-guide-swift3/_migration-guide.md
+  - documentation/migration-guide-swift3/se-0107-migrate.md
+- documentation/migration-guide-swift4/index.md
+  - documentation/migration-guide-swift4/_migration-guide.md
+- documentation/migration-guide-swift4.2/index.md
+  - documentation/migration-guide-swift4.2/_migration-guide.md
+- documentation/migration-guide-swift5/index.md
+  - documentation/migration-guide-swift5/_migration-guide.md
+- documentation/source-code/index.md
+- documentation/source-compatibility/index.md
+- documentation/server/guides/memory-leaks-and-usage.md
+- documentation/server/guides/allocations.md
+- documentation/server/guides/linux-perf.md
+- documentation/server/guides/performance.md
+- documentation/server/guides/llvm-sanitizers.md
+- documentation/server/guides/packaging.md
+- documentation/server/guides/packaging.md
+- documentation/server/guides/passkeys.md
+- documentation/server/guides/libraries/log-levels.md
+- documentation/server/guides/libraries/concurrency-adoption-guidelines.md
+- documentation/server/guides/deployment.md
+- documentation/server/guides/deploying/aws-sam-lambda.md
+- documentation/server/guides/deploying/aws-copilot-fargate-vapor-mongo.md
+- documentation/server/guides/deploying/aws.md
+- documentation/server/guides/deploying/aws.md
+- documentation/server/guides/deploying/digital-ocean.md
+- documentation/server/guides/deploying/ubuntu.md
+- documentation/server/guides/deploying/heroku.md
+- documentation/server/guides/deploying/gcp.md
 - documentation/swift-compiler/index.md
   - documentation/swift-compiler/_compiler-architecture.md
 - documentation/standard-library/index.md