Angular-cli: Documentation is lacking

[axelboc]

Bug Report or Feature Request (mark with an x)

- [ ] bug report -> please search issues before submitting
- [ ] feature request
- [x] documentation request

Versions

@angular-devkit/architect         0.6.8
@angular-devkit/build-angular     0.6.8
@angular-devkit/build-optimizer   0.6.8
@angular-devkit/core              0.6.8
@angular-devkit/schematics        0.6.8
@angular/cli                      6.0.8
@ngtools/webpack                  6.0.8
@schematics/angular               0.6.8
@schematics/update                0.6.8
rxjs                              6.2.0
typescript                        2.7.2
webpack                           4.8.3

Desired functionality

The documentation of the CLI is tremendously lacking. This is not the first issue talking about it and, until the problem is properly addressed, it won't be the last. Here are some of the problems I've come across:

• The wiki is out of date and, therefore, unreliable.

Example: ng serve is said to have a --verbose option, but when I run ng serve --verbose, I get an error: "Unknown option: '--verbose'". If an option as simple as verbose is improperly documented, how can I trust anything else on the wiki? When I'm confronted with a problem, how do I know whether I made a mistake or the documentation mislead me?

• A JSON schema is not a documentation.

Sure it's good to have, but it doesn't actually explain much, especially when the description of each option doesn't provide any useful info. Example: the description of ng build's --configuration option is "Specify the configuration to use."

• Many of the "stories" have nothing to do with Angular CLI

Why are there stories for Angular Material, Font Awesome and other libraries ? The stories that actually relate to the CLI, like "Multiple projects" are more difficult to spot, especially since they are listed in no meaningful order. Stories are also not a replacement for proper documentation of commands, options and workflows.

• A wiki may not be the best way to store documentation

1. It makes it difficult to organise pages into a proper, navigable structure.
2. It has very limited versioning capabilities. For instance, it's not possible (to my knowledge) to see all the changes that were made to the entire wiki between two releases of the CLI.
3. Changes to the documentation are not announced in a change log or in the release notes, which is probably a consequence of the previous point.

[alexeagle]

+1 to all of that. We're working on it! A few things that will help:

• we are working to have CLI documentation on angular.io https://github.com/angular/angular/pull/25363
• we'll put some effort into improving the JSON schema fields and using these to drive things like the help in Angular Console

[thepian]

It would be great if the config for package.json were documented. It's becoming ever harder to get things right. As an example I have the following

    "@angular-devkit/build-angular": "~0.7.3",
    "@angular-devkit/build-optimizer": "~0.7.3",
    "@angular/cli": "6.1.3",
    "@angular/compiler": "6.1.3",
    "@angular/compiler-cli": "6.1.3",
    "@angular/language-service": "6.1.3",
    "@ngtools/webpack": "6.1.3",

This seems to pull in versions of dependencies across 0.7.3 0.7.4 6.1.3 and 6.1.4

Am I actually just supposed to put in "@angular/cli": "6.1.3", or the full list.

[axelboc]

Closing, since the CLI docs are now officially here: https://angular.io/cli/, the --verbose option works as intended, and all the commands and options seem to be better documented. Thanks for the awesome work!!

@thepian, this page clarifies a few things: https://angular.io/guide/npm-packages -- not sure if it's what you were after. If not, might be worth opening a more specific issue.

[angular-automatic-lock-bot[bot]]

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{_This action has been performed automatically by a bot._}