Inconsistent package manager install / add instructions

Question

Inconsistent package manager install / add instructions

MikeMcC399 opened this issue 3 months ago · comments

Mike McCready commented 3 months ago

Subject

Multiple pages using npm install, pnpm add and yarn add

Description

Issue

Instructions for installing cypress and other npm modules are shown inconsistently throughout the website for npm, pnpm and Yarn package managers.

Sometimes the short-form of an optional flag is used and sometimes the long-form is used, e.g.
- Component Testing > Getting Started > Install Cypress uses -D:
```
npm install cypress -D
```
- Getting Started > Installing Cypress > npm install uses the equivalent --save-dev:
```
npm install cypress --save-dev
```
Sometimes an optional flag is positioned directly after install and sometimes the same optional flag is positioned at the end of line, e.g.

Continuous Integration > Introduction > Setting up CI > Boot your server > Solutions uses --save-dev directly after install:
```
npm install --save-dev start-server-and-test
```
Continuous Integration > Introduction > Setting up CI > Basics uses --save-dev at the end of line:
```
npm install cypress --save-dev
```

Suggestions

Each of the examples are correct, however making the instructions consistent throughout the site avoids causing confusing about whether any differences are significant or not.

Suggest to standardize on long form for optional flags, e.g. --save-dev. This makes for better comprehension for readers unfamiliar with the meaning of the alternative short-form optional flag.
Align the positioning of the optional flag to the package manager documentation. For instance, npm CLI > npm-install > Description shows --save-dev used at the end of the line in its example:
```
npm install node-tap --save-dev
```

Most of the examples use npm install. A few examples use yarn add and just one example uses pnpm add.

Mike McCready · Answer 1 · Mon Mar 25 2024 22:35:33 GMT+0800 (China Standard Time)

If the suggestions I made are acceptable then I will submit a PR to implement them. Please let me know if this should be done and if the individual suggestions are OK.

Jennifer Shehane · Answer 2 · Mon Mar 25 2024 22:52:47 GMT+0800 (China Standard Time)

@MikeMcC399 Yep, exactly the same recommendations I was going to suggest. Definitely want things easier to follow for people more unfamiliar with package managers.

Mike McCready · Answer 3 · Mon Mar 25 2024 23:59:32 GMT+0800 (China Standard Time)

@jennifer-shehane

Thanks for your feedback and agreement!

#5765 is now submitted to propose this documentation improvement.