Docs: Libraries ecosystem: developer workflows and guidelines

Start with the Libraries overview at angular.dev/tools/libraries and compare its sub-pages, especially creating-libraries, using-libraries, and angular-package-format. Review the related context in #70830 and angular/angular-cli#34106 before outlining the proposed workflow-focused structure. Done means the documentation explains when to create a library, distinguishes workspace-local and npm-published libraries, and adds the requested publishing and entry-point guidance.

Describe the problem that you experienced

Context of this issue:

• #70830
• angular/angular-cli#34106

The Libraries documentation (incl. its sub-pages) as of today are a rather mechanical description what a library is, what can be done with it, mentioning there is an architectural decision around creating a library.

Enter the URL of the topic with the problem

https://angular.dev/tools/libraries

Describe what you were looking for in the documentation

With the new Angular library builder on the horizon, it's a good point in time to look at the libraries documentation again.

I will say that most of the time developers are users of libraries. Creating and publishing a library affects developers less frequently. I propose to re-phrase the libraries documentation to address the developers workflow and put more emphasis on guidelines rather than mechanical how tos.

Describe the actions that led you to experience the problem

No response

Describe what you want to experience that would fix the problem

Proposal for new-looking libraries documentation pages.

When to create a Library (vs. when not)

Instead of just mentioning whether to create or not to create a library is an architectural decision, the documentation should list decision criteria when to create a library and the consequences of it. This is not only a binary decision ("when to..." vs. "when not to..."), but also is a decision of when to create library published to npm" vs. "when to create a workspace-local library" (like the Nx monorepo pattern for sharing libraries through path mappings) vs. "when not to create a library".

Using vs. Creating a Library

A second point is to re-phrase the libraries documentation with an emphasis on library users (consumers), following the same pattern of the Angular elements docs. The starting page of the "Libraries" docs has a headline "Overview" and "Creating libraries". I propose to structure the Overview page:

• What is a library?
  • Shorten the intro
  • Libraries vs. custom elements
• How to use a library?
  • Example
  • Cross-reference to ng update schematics
• Creating a library
  • When to create a library
  • Deciding on workspace-local (monorepo pattern) vs. publishing to npm
  • Example for creating a library with ng generate library

Sub Pages of the libraries documentation:

• Creating libraries
  • Focus on "publishable to npm"-libraries
  • Add "Versioning" and "Release": Semver, Conventional Commits as a guideline, Changelogs, link to external tools such as standard-version or semantic-release
  • Creating libraries with the ng CLI: keep most of the How To-instructions intact (I think it's quite good), wrapping up with references to community documentation around library workflows
  • Entry points: primary entry points and secondary entry points, when to use, why to use, example
• Using Libraries and Angular Package Format: keep as is

Add a screenshot if that helps illustrate the problem

No response

If this problem caused an exception or error, please paste it here

If the problem is browser-specific, please specify the device, OS, browser, and version

Provide any additional information here in as much as detail as you can