Skip to content

Improve npm documentation

Katie Macoy requested to merge standardize-package-docs into master

What does this MR do and why?

This MR is part of a series:

We are the in the process of simplifying the Package Registry documentation.

  • ✅ Step 1: !103289 (merged) Adds a new page with how to build packages, per format
  • ✅ Step 2: gitlab-docs!3266 (merged) Adds the new build page to the navigation
  • ✅ Step 3: !104034 (merged) Removes build information from each package format page and links from the package format page to the new build page
  • 🎱 Step 4: This MR. Rewrites npm documentation

The purpose of this MR is to reduce the overall amount of content on each package format and have each package format page contain only the most essential information. (More information in #376359)

Our goal is to standardize the format of each package format page and I thought I would tackle a single format (npm) first to set the structure of the page.

The structure proposed is:

  • introduction
  • publish a package
    • via command line
    • via ci/cd
  • install a package
  • helpful hints
  • troubleshooting

Notes about this MR:

  • It removes a lot of information. For example, there are multiple ways of doing things in npm, but I focused on only explaining how to do things in 1 way.
  • Removes all information like Introduced in GitLab 14.5...
  • Guidance for authentication in .npmrc focuses on not hard coding variable in .npmrc
  • I moved the authentication information into the steps themselves (publish, install)
  • I removed all yarn information and I will create another MR that adds a page specifically for yarn
  • I tried to be a bit more specific about @scope requirements
  • Links to token information rather than listing in the page itself

Screenshots or screen recordings

Before After
prodnpm_packages_in_the_Package_Registry___GitLab npm_packages_in_the_Package_Registry___GitLab

How to set up and validate locally

  1. Enable gitlab docs in the gdk https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/gitlab_docs.md
  2. Visit npm package format page

MR acceptance checklist

This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Katie Macoy

Merge request reports