📚[DOCS]: Documentation needs more complete examples

[isochronous]

Description

Most of the documentation around selectors is very targeted around the usage of specific methods, but there is a lot of information required for real-world use that is just missing.

For example, the docs describe a bunch of different ways of defining selectors using @Selector. Then they show a bunch of ways of defining selectors using Select. But you don't actually explain the relationship between the two, or if @selectors can be defined in component classes as well, or if they can only use @Select and @Selector has to be used in state or library classes only. Like, I assume because the examples all show @Selector only being used in state classes or "meta-selector" classes, that they cannot be used in component classes that consume the state. But I don't actually KNOW, because the docs don't actually cover that, they just give a bunch of different examples.

Then on your "optimizing selectors" page you spend a great deal of time showing how to define an isDataSelected lazy selector, but DO NOT SHOW HOW TO USE IT in the component. In fact, I cannot find a single place in the documentation where you explain how to use lazy selectors like this. The only place where there is code showing an example of using a lazy selector, you're using a pattern that I do not think would work with the isDataSelected lazy selector?

@Component({ ... })
export class ZooComponent {
  babyPandas$: Observable<string[]>;

  constructor(private store: Store) {
    this.babyPandas$ = this.store
      .select(ZooState.pandas)
      .pipe(map(filterFn => filterFn('baby')));
  }
}

What's the affected URL?**

https://www.ngxs.io/concepts/select
https://www.ngxs.io/advanced/optimizing-selectors

Expected vs Actual Behavior**

Documentation really needs to be more holistic, not only showing how to define aspects of the state, but ALSO show how those aspects can be consumed within related components. API documentation for the various decorators and primary classes would also be very welcome (I feel like this HAS to exist already, but I haven't found it). Trying to figure out all of the various signatures for the decorators involves a whole lot of clicking around through various pages.

Having multi-tab examples like angular material does would be very useful, where a single example could include both the state pieces being defined and the consumption of those pieces in component logic and/or templates.

[markwhitfeld]

Hi Jeremy Thank you so much for the feedback, and for being specific with the area and topic that needs attention. We are definitely aware that there are a number of areas in our docs that could be a lot better. In our development version of the docs we have started with a high level restructuring, and are making improvements to tell a better story. I will raise this in our next team meeting. I welcome any more recommendations you may have, as you work through the different areas of the docs, and if you have any improvements that are best expressed as a PR contributing to the docs, that would be amazing!

…

On Tue, 14 May 2024 at 19:39, Jeremy McLeod ***@***.***> wrote: Description Most of the documentation around selectors is very targeted around the usage of specific methods, but there is a lot of information required for real-world use that is just missing. For example, the docs describe a bunch of different ways of defining selectors using @selector. Then they show a bunch of ways of defining selectors using Select. But you don't actually explain the relationship between the two, or if @selectors <https://github.com/selectors> can be defined in component classes as well, or if they can only use @select and @selector has to be used in state or library classes only. Like, I assume because the examples all show @selector only being used in state classes or "meta-selector" classes, that they cannot be used in component classes that consume the state. But I don't actually KNOW, because the docs don't actually cover that, they just give a bunch of different examples. Then on your "optimizing selectors" page you spend a great deal of time showing how to define an isDataSelected lazy selector, but DO NOT SHOW HOW TO USE IT in the component. In fact, I cannot find a single place in the documentation where you explain how to use lazy selectors like this. The only place where there is code showing an example of using a lazy selector, you're using a pattern that I do not think would work with the isDataSelected lazy selector? @component({ ... }) export class ZooComponent { babyPandas$: Observable<string[]>; constructor(private store: Store) { this.babyPandas$ = this.store .select(ZooState.pandas) .pipe(map(filterFn => filterFn('baby'))); } } What's the affected URL?** https://www.ngxs.io/concepts/select https://www.ngxs.io/advanced/optimizing-selectors Expected vs Actual Behavior** Documentation really needs to be more holistic, not only showing how to define aspects of the state, but ALSO show how those aspects can be consumed within related components. API documentation for the various decorators and primary classes would also be very welcome (I feel like this HAS to exist already, but I haven't found it). Trying to figure out all of the various signatures for the decorators involves a whole lot of clicking around through various pages. Having multi-tab examples like angular material does would be very useful, where a single example could include both the state pieces being defined and the consumption of those pieces in component logic and/or templates. — Reply to this email directly, view it on GitHub <#2166>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAO3U2MFGC4E47BEJEIV7O3ZCJD4PAVCNFSM6AAAAABHWUCMY2VHI2DSMVQWIX3LMV43ASLTON2WKOZSGI4TMMBSGIYTAMI> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>