Add a "Guides" section

[achrinza]

Suggestion

Add a "Guides" section in the docs, just like how there is a "Examples" and "Core Concepts" section.

Use Cases

"Core Concepts" can only provide information in a vacuum (within that concept).

"Examples" provides a complete guide to making a specific application.

Hence a "Guides" section would fill the gap for more general detailed information on common scenarios, such as:

• Implementing a socket.io server
• Manually modifying Request and Response
• Handling file uploads
• Handling file downloads
• Using a model with multiple datasources

Acceptance criteria

TBD - will be filled by the team.

[dhmlau]

@achrinza, thanks for the suggestion. Would the "Guide" you suggested be something similar to the Usage Scenario in the docs?

[achrinza]

@dhmlau You're right; they're similar. Initially I thought that "Usage Scenarios" was a high-level overview of LoopBack 4 features.

Should we rename it to "Guides"? It seems to be better-associated to the purpose of the section. I'm not not hard-set on the change, but that's my suggestion.

[derdeka]

@achrinza Initially when reading your ticket i thought you would suggest a kind of FAQ to support answering user issues. So you want full featured "Guides"?

[achrinza]

@derdeka A FAQ wasn't what I initially had on mind, but I think we can create a story for that: A FAQ may be able to fill in a different gap in the docs.

[dhmlau]

Renaming "Usage Scenarios" to "Guides" LGTM. Let me see if I get the differences from all the categories:

• Key concepts: explain what certain concept is and how it relate to other concepts
• Examples: just examples on how to do certain things. Not step-by-step instructions
• Tutorials: step-by-step instructions on how to to do
• Guide: "how-to" information.

I think:

• What we have in "Usage scenarios" seem to fit in the "Guide" category
• The question would be: Some of the items under Using Components seems to fall under "Guide" as well. In fact, authentication and authorization exist in both categories. Do we want to combine the two?

I'd also like to hear from other maintainers @strongloop/loopback-maintainers as well. Thanks!

[achrinza]

@derdeka Aparently there's already an FAQ. It's referenced in the README but not on the lb4 sidebar.

[achrinza]

My concern with the Authentication and Authorizations docs is that they're quite overloaded with information. It may make it difficult to get a good overview on the different features an configuration styles of those components.

I think those pages (Authentication, Authorization) should be at a higher level - more focused on the features and configurations that are possible, and then linking to the respective guides for a more in-depth explanation

Hence a "guides" section would make increase the readability of the docs.

[dhmlau]

@achrinza, given the current docs improvement effort, we've added a few guides as "how-tos" and "references". Do you think we can close this issue and continue discussions in specific docs epics? Thanks.