Improve SwiftPM Example Usage

We can improve the SwiftPM Example Usage Guide to make it easier for newcomers to grasp important things about the Package Manager.

I will make observations/suggestions per section.

Suggestions

0. It would be nice for the page to have an index

With an index it would be more discoverable that there's an "Example Usage" below and what the guide covers.

1. Creating a Library Package

I think this section needs a better introduction. Instead of starting with a code sample, it would be better to explain the structure of a Library Package first, and make it explicit that you can run swift package init if you want the Package Manager to build the file structure for you.
Then we can introduce the sample code and so on.

I suggest this because it would be confusing when you start with a snippet of code. Newcomers can face questions as:

  1. Where should I write this code?
  2. How is this supposed to be part of a "Package"?
  3. Ok I am writing code but, where's my "Library"?

and that can be confusing.

Maybe they are similar questions, but they make my intention clear.

Code snippet observation

Another observation is to the snippet of code which is not complete.

It this unpleasant to follow a guide and at the end your results are not the same.

Although there's a quote that tells where the complete code is located, I think that notice does not make it clear that you need to go to GitHub and complete your code in order to get the same result as in the guide.

This led me to propose two solutions:

  1. A "warning" that makes explicit that your output will not be the same as in the Guide if you don't go to GitHub and complete your code.

  2. Include the complete updated code on the page under a "hide/show detail" option.

2. Using Build Configuration Statements

It would be nice if we make it clear that FisherYates can be created just as PlayingCard, running swift package init.

If we want people to create the project structure by themself for better understanding, we can show them to do it in the first section and then show them swift package init in the second section.

Same notes as in code snippet observation in the first section
Summary
Code snippet observation

Another observation is to the snippet of code which is not complete.

It this unpleasant to follow a guide and at the end your results are not the same.

Although there's a quote that tells where the complete code is located, I think that notice does not make it clear that you need to go to GitHub and complete your code in order to get the same result as in the guide.

This led me to propose two solutions:

  1. A "warning" that makes explicit that your output will not be the same as in the Guide if you don't go to GitHub and complete your code.

  2. Include the complete updated code on the page under a "hide/show detail" option.

3. Importing Dependencies

The second paragraph of this section says:

To use the FisherYates and PlayingCards modules, the DeckOfPlayingCards package must declare their packages as dependencies in its Package.swift manifest file.

It would be better to add a quick note making clear where should the Package.swift be located.

Same notes as in code snippet observation in the first section
Summary
Code snippet observation

Another observation is to the snippet of code which is not complete.

It this unpleasant to follow a guide and at the end your results are not the same.

Although there's a quote that tells where the complete code is located, I think that notice does not make it clear that you need to go to GitHub and complete your code in order to get the same result as in the guide.

This led me to propose two solutions:

  1. A "warning" that makes explicit that your output will not be the same as in the Guide if you don't go to GitHub and complete your code.

  2. Include the complete updated code on the page under a "hide/show detail" option.

4. Resolving Subdependencies

Two suggestions similar to the ones before:

  1. It should talk about how SwiftPM can generate the project structure for you specifying swift package init --type executable.
  2. Same notes as before for the incomplete snippet of code.
5 Likes
Terms of Service

Privacy Policy

Cookie Policy