While following along with the documentation, I stumbled setting up a Package.swift for the example, and ran into some odd errors when I missed a dependency (filed bug https://bugs.swift.org/browse/SR-14459), so I thought the documentation would benefit from an example directory to make it easier for others to follow along and learn how to use this library. I made the example content such that the command-line examples in the docs should be easy to quickly follow and reproduce locally, and otherwise it's stock swift package init content.
While I'm far from a professional editor, I also went through and made some language changes — removing some instances of 'simply' and 'just' — and reframing a few places out of passive voice where it seemed beneficial to be more direct. I tried to not change everything in order to keep the original, personal, voice of the doc intact.
I've left the wording edits as separate commits in this PR, so they can be easily dropped from the PR if you don't find them appropriate. I used to use both 'simply' and 'just' quite frequently myself, thinking it made things more approachable and less scary, but have recently learned (and converted to the idea) that they can often have the reverse effect, especially for novice, confused, or frustrated readers.
lorentey
commented
3 years ago
While following along with the documentation, I stumbled setting up a Package.swift for the example, and ran into some odd errors when I missed a dependency (filed bug https://bugs.swift.org/browse/SR-14459), so I thought the documentation would benefit from an example directory to make it easier for others to follow along and learn how to use this library. I made the example content such that the command-line examples in the docs should be easy to quickly follow and reproduce locally, and otherwise it's stock
swift package initcontent.While I'm far from a professional editor, I also went through and made some language changes — removing some instances of 'simply' and 'just' — and reframing a few places out of passive voice where it seemed beneficial to be more direct. I tried to not change everything in order to keep the original, personal, voice of the doc intact.
I've left the wording edits as separate commits in this PR, so they can be easily dropped from the PR if you don't find them appropriate. I used to use both 'simply' and 'just' quite frequently myself, thinking it made things more approachable and less scary, but have recently learned (and converted to the idea) that they can often have the reverse effect, especially for novice, confused, or frustrated readers.
Checklist