Installation Section Best Practices

Installation Section Best Practices

The installation section is where many potential users decide to continue or abandon your project. Clear, working installation instructions are non-negotiable.

Show Multiple Package Managers

## Installation

Using npm:
\`\`\`bash
npm install my-package
\`\`\`

Using yarn:
\`\`\`bash
yarn add my-package
\`\`\`

Using pnpm:
\`\`\`bash
pnpm add my-package
\`\`\`

Distinguish Dev Dependencies

If the package is only needed for development:

npm install --save-dev my-linter

Global vs Local Installation

For CLI tools, explain the difference:

### Global Installation (recommended for CLI usage)
\`\`\`bash
npm install -g my-cli
\`\`\`

### Local Installation (for project-specific usage)
\`\`\`bash
npm install my-cli
npx my-cli <command>
\`\`\`

System Requirements

List requirements before the install command:

### Requirements
- Node.js 18 or higher
- npm 9 or higher
- Python 3.8+ (for native modules)

Platform-Specific Instructions

If installation differs by platform:

### macOS
\`\`\`bash
brew install my-tool
\`\`\`

### Linux
\`\`\`bash
curl -fsSL https://get.my-tool.dev | bash
\`\`\`

### Windows
\`\`\`powershell
winget install my-tool
\`\`\`

Verify Installation

Always include a verification step:

my-tool --version
# Expected output: my-tool v2.1.0

Troubleshooting

Add a brief troubleshooting section for common installation issues:

• Permission errors: suggest --user or fix npm prefix
• Native module build failures: point to prerequisites
• Version conflicts: suggest using nvm