Eliminate duplicate instructions?

[gandalfas]

This is a concern regarding the Swift installation procedure. Below, after describing the issue, I have a request to change Swift - Getting Started and/or Download. I am new at Swift, and other thoughts are welcome! And many thanks to all who helped bring Swift to Windows!!! :)

Environment

build number: Swift 5.6.1
OS: Windows 10 desktop computer

Feature Description

Would it be possible to eliminate some duplicated instructions?

The complete install instructions are currently on both Swift - Getting Started and Download. It would seem wiser to store the instructions in only one place. Could one of these pages be the sole location and the other simply link to that?

Rationale: I am in the process of submitting a number of change requests to the installation procedure on these documentation pages, so this suggestion will have two benefits: 1) it will be less maintenance, and 2) it just keeps them from getting out of sync (the DRY principle).

Suggested Documentation Fixes

At the top of Swift - Getting Started,
change this:
The first step to using Swift is to download and install the compiler and other required components. Go to the Download page and follow the instructions for your target platform.

to this:
The first step to using Swift is to download and install the compiler and other required components. Go to the Download page to download the release of your choice, then follow the instructions below for your target platform.

Or, if you prefer, you could flip that and keep the instructions only on Download.

Also, while problem solving my install, I was directed to a third set of instructions:

pwsacademy swift-setup

by the page When I install swift correctly....

Would you consider merging any valuable install information on that first page into the official install instructions page? Especially the "Known Issues".

[gandalfas]

Update, 1 year later:

I see that the install instructions for Windows on Swift - Getting Started and Download are currently out of sync, at least for Windows. For example, "Enabling Developer Mode" is only in the former.

So my above comments are no longer quite correct, because they assumed the instructions were identical. Please reinterpret the above Suggested Doc Fix to mean that the install instructions will need careful merging before deleting one copy, so as not to lose any information.

Also note that I have issues #286 and #287 which request changes to Swift - Getting Started, so it would be most efficient to complete this issue first.

Finally, @AnthonyLatsis, could you please transfer this issue from apple/swift to swift-org-website? Thanks!

[AnthonyLatsis]

@shahmishal Please transfer this issue to swift-org-website for us.

[alexandersandberg]

Hey @gandalfas, we've made some improvements on this in our content improvements initiative which is now ready for review: #354

We would appreciate your feedback there! 🙂

[gandalfas]

Hey @alexandersandberg, Thanks for the work, and the invitation for feedback! I have added comments there.