broad swiftly-doc content edit pass #268
Conversation
- switched article titles to not use capitals all across - made use of `swiftly` more consistently lower-case, including titles - revised language in a few places to remove future or past tense phrasing or to make the wording more direct. - broke up the paragraphs into one-sentence-per-line structure for easier reviewing. - fixed an odd typo. - tried to broadly maintain the existing voice, but remove some extra phrasing here and there and generally tighten up the content.
| tar zxf swiftly.tar.gz | ||
| ``` | ||
|
|
||
| On macOS you can download the pkg file and extract it like this from the command-line: | ||
| On macOS, download the pkg file and extract it like this from the command-line: | ||
|
|
||
| ``` | ||
| curl -L <location_of_swiftly_swift_org> > swiftly.pkg |
There was a problem hiding this comment.
question: Now that the download URL's are established, can you update this curl command here for macOS too?
|
|
||
| ``` | ||
| installer -pkg swift-x.y.z.pkg -target CurrentUserHomeDirectory | ||
| ``` | ||
|
|
||
| Now run swiftly init to finish the installation: | ||
| Once the package is installed, run `swiftly init` to finish the installation: | ||
|
|
||
| ``` | ||
| ~/usr/local/bin/swiftly init |
There was a problem hiding this comment.
question: since you're revamping the documentation now that things are settled, such the default location of the swiftly binary in the macOS .pkg file, can you update this path to be ~/.swiftly/bin/swiftly init?
| @@ -72,10 +74,10 @@ Uninstall this toolchain after you're finished with it: | |||
| $ swiftly uninstall main-snapshot | |||
| ``` | |||
|
|
|||
| # Proxy | |||
| # Installing toolchains through a proxy | |||
There was a problem hiding this comment.
suggestion: Maybe we should use the term "HTTP Proxy" here so that people don't confuse it with swiftly's toolchain binary proxy mechanism?
| @@ -20,21 +20,23 @@ To get started with swiftly you can download it from [swift.org](https://swift.o | |||
| } | |||
|
|
|||
| @Tab("macOS") { | |||
| On macOS you can either run the pkg installer from the command-line like this or just run the package by double-clicking on it (not recommended): | |||
| On macOS you can either run the pkg installer from the command-line like this or run the package by double-clicking on it (not recommended): | |||
|
|
|||
| ``` | |||
| installer -pkg swift-x.y.z.pkg -target CurrentUserHomeDirectory | |||
There was a problem hiding this comment.
question: can the pkg file name be fixed here too? It's mistakenly written as swift-x.y.z.pkg when it should be swiftly-x.y.z.pkg.
|
@cmcgee1024 I added some revision of the Getting Started page in swiftly's docs to more closely mirror what's on the swift.org install pages. In particular, I dropped the swiftly-x.y.z.tar.gz structure, since it looks like this installer-to-install-swiftly wasn't released with versions embedded in its name. That does highlight that there's a lot of repetition with the "getting started" docs and what's on in https://www.swift.org/install/linux/ & https://www.swift.org/install/macos/ The getting started doesn't mention explain this bit from the "install" page details though: The env portion IS covered in shell-autocompletion, but we don't guide folks there, and we don't mention much of anything about the |
The swift website is focused more on getting users up and running very quickly, so it tries to accelerate them past all of the shell update commands too. I think for here we can rely more on swiftly itself informing the users of the followup commands. Let swiftly do the heavy lifting of guiding the users to help with documentation that may be more mismatched with the implementation. |
|
This looks great, thanks for the reworking the documentation @heckj. |
swiftlymore consistently lower-case, including titles