[docs] Adopt four-quadrant documentation system

[bajtos]

As the first step on a longer journey to rearrange & improve our docs as discussed in #5549, I am proposing to re-arrange the sections in our sidebar as follows:

• Merge all Explanation pages under "Behind the scene" (Remove "Key Concepts" from the sidebar, move the content of
  Concepts.md to Behind-the-scene.md).
• Move tutorials higher up in the sidebar
• Nest all Reference guides under "References" entry in the sidebar, rename the entry to "Reference guides"
• Move "Using components" entries to "Usage scenarios", remove "Using components" page altogether and move the relevant content to "Components" page in Behind the scene section.
• Rearrange top sidebar entries in a slightly different order

Screenshot of the proposed sidebar:

I was not able to find any quick & easy way how to create an online preview of the new doc version, please run npm docs:prepare && npm docs:start to start preview locally on you computer.

Please note I don't consider this as the ultimate final version, I am expecting us to iterate on the structure in the near future, as part of Documentation improvements 2020Q3 #5113.

Checklist

👉 Read and sign the CLA (Contributor License Agreement) 👈

• npm test passes on your machine
• New tests added or existing tests modified to cover all changes
• Code conforms with the style guide
• API Documentation in code was updated
• Documentation in /docs/site was updated
• Affected artifact templates in packages/cli were updated
• Affected example projects in examples/* were updated

👉 Check out how to submit a PR 👈

[bajtos]

Few more screenshots to make the review easier:

[dhmlau]

Thanks for kicking off this effort. The changes are generally LGTM. Perhaps a few points for discussion, we don't necessarily need to do it in this PR:

• Key concepts
  • I kind of like the "Key concepts" item in the sidebar in a way to indicate those are the first 5-6 concepts the users need to know. :) In the todo tutorial, there's some descriptions of the those concepts which I think are sufficient for this purpose.
• "Behind the scene" and "Usage Scenario"
  • it's a long list under those sections. Not sure if there's a better way to group them in the sidebar, or maybe as long as we categorize them in the parent page would be good.

[agnes512]

Thanks for taking the first step!

Move tutorials higher up in the sidebar

👍

How I review this PR is to see if it makes sense to add 'how to' to the items under usage scenarios and add ' what is' to the items under Behind the scenes. Most of them look good to me except the Using express middleware entry under behind the scenes. For me, the title and its content are more like usage scenarios.

Another concern is the connectors reference entry. It's a bit weird to see it under references because they are actually mixed with how tos and tutorials 🙈 I am okay to leave as it and find a better way in the future.

[dhmlau]

Another concern is the connectors reference entry. It's a bit weird to see it under references because they are actually mixed with how tos and tutorials 🙈 I am okay to leave as it and find a better way in the future.

Would it be a good chance to move those connector-related tutorials to the Tutorial umbrella?

[jannyHou]

List More useful info in the root level menu?

inspired by #5113 (comment)
A comparison between ours and RxJS: I like how they unfold and display some core concepts(each in one word) when page loads, to give readers an impression of what the framework does without looking into any details.

(I don't find a good candidate in the root level menu to unfold: "behind the scene" has a long list, others don't list sub-sections in a certain order. But the items in "Inside a LoopBack Application" is close to what I am looking for. )

Here is a list of the most basic concepts I could think of that makes at least REST API developers understand what this framework offers:

App --> Model --> Datasource --> Repository --> Controller --> API Explorer --> Relation --> Security --> Deploy
(Just an example)

Maybe we can refactor "Inside a LoopBack Application" to display ^ in the menu?

Highlight "REST framework" and "More powerful beyond REST"

And I also like @hacksparrow 's point in #5551, agree to make "REST framework" and "More powerful beyond REST" obvious enough.

Maybe in the overview section, we can have 2 sub sections:

• "REST framework"(or a better name) : a page summarizes and lists all REST related concepts/tutorials/user scenarios
• "More than REST"(or a better name) : a page summarizes and lists all concepts/tutorials/user scenarios for extensibility.

---

My suggested sidebar will look like

[jannyHou]

👏 Nice start!! I like the new structure, post two suggestions in comment #5718 (comment), in terms of giving readers a more clear impression of what our framework offers without looking into details.

sorry joined the doc discuss late :p hope I catched up all the discussions and the suggestions are not off topic.

[jannyHou]

A thought: I see frameworks like angular uses word "Techniques" , I think it describes the same concept and concise as well.

[bajtos]

I don't think Angular is a good source of inspiration. When I look at their docs for Animation technique, I see a mix of tutorials, explanations and how-to guides. In my PR, I am trying to move away from that style.

Maybe "Fundamentals" would be a better term to borrow from them, but then our "Behind the scenes" content goes far beyond fundamental concepts.

[hacksparrow]

I kind of like the "Key concepts" item in the sidebar in a way to indicate those are the first 5-6 concepts the users need to know. :) In the todo tutorial, there's some descriptions of the those concepts which I think are sufficient for this purpose.

Yes, "Key Concepts" was like a reliable go-to help for the confused souls. Clubbing everything under "Behind the Scenes" is taking away the anchor and adding to the confusion. Also, I am not very convinced by the name "Behind the Scenes".

[bajtos]

Thank you for the feedback!

Key concepts
I kind of like the "Key concepts" item in the sidebar in a way to indicate those are the first 5-6 concepts the users need to know. :) In the todo tutorial, there's some descriptions of the those concepts which I think are sufficient for this purpose.

The page Inside a LoopBack Application is explaining the first 5-6 concepts the users need to known. I found the content in "Inside a LoopBack application" as well structured for new LoopBack users and don't feel the need to create dedicated "key concepts" entries in the left sidebar.

Can we perhaps find a better name than "Inside a LoopBack Application", one that will make it easier for new users to understand what content to expect in that page and also that this is the page to read when they want to learn about the basic concepts?

Behind the scene" and "Usage Scenario"
it's a long list under those sections. Not sure if there's a better way to group them in the sidebar, or maybe as long as we categorize them in the parent page would be good.

I agree the list is too long. I'd like to introduce grouping based on functional areas/usage scenarios (e.g. "build REST API", "access data", "prepare for production", etc.), but let's do that in a follow-up issue, so that we can discuss which page belongs where and what other updates are needed as part of those changes.

title: 'Considerations for GDPR readiness'
Perhaps we can put this after "Change logs".

I feel the GDPR page is a bit of an odd-ball. I think it would be better to rework that page to become a How-to guide, something like "Make your application GDPR compliant". WDYT? Such change would be out of scope of this PR though, but I can open a follow-up issue if we think this is something to make happen.

BTW should we create a similar page for California Consumer Privacy Act considerations? Maybe rework the GDPR page into a broader page "Make your app compliant with privacy regulations"?

Anyhow, in this PR, I'll simply follow your suggestion and list the current page after Change logs.

How I review this PR is to see if it makes sense to add 'how to' to the items under usage scenarios and add ' what is' to the items under Behind the scenes. Most of them look good to me except the Using express middleware entry under behind the scenes. For me, the title and its content are more like usage scenarios.

Good catch! I am going to open follow-up issues to reorganize existing content along "how-to" vs "what is" axis, but since "Using express middleware" is already written in how-to style, I'll move the page to "how-to" section in the sidebar.

Another concern is the connectors reference entry. It's a bit weird to see it under references because they are actually mixed with how tos and tutorials 🙈 I am okay to leave as it and find a better way in the future.

Good point 👍 I'll keep this in mind when creating follow-up stories to untangle pages mixing different kinds of content.

Would it be a good chance to move those connector-related tutorials to the Tutorial umbrella?

Let's leave that out of scope of this PR please. I'll open a follow-up issue (or epic).

List More useful info in the root level menu?
A comparison between ours and RxJS: I like how they unfold and display some core concepts(each in one word) when page loads, to give readers an impression of what the framework does without looking into any details.
(I don't find a good candidate in the root level menu to unfold: "behind the scene" has a long list, others don't list sub-sections in a certain order. But the items in "Inside a LoopBack Application" is close to what I am looking for. )

I see how it can be useful to be able to get an impression of what the framework does at high level.

I am not convinced though that the sidebar is the right place for this kind of information. IMO, we should provide such overview on one of the introductory pages, e.g. "Inside a LoopBack Application" you mentioned or perhaps on the landing page (see Overview).

I'll open a follow-up issue to continue this discussion and find a good solution.

Highlight "REST framework" and "More powerful beyond REST"
And I also like @hacksparrow 's point in #5551, agree to make "REST framework" and "More powerful beyond REST" obvious enough.

Maybe in the overview section, we can have 2 sub sections:

• "REST framework"(or a better name) : a page summarizes and lists all REST related concepts/tutorials/user scenarios
• "More than REST"(or a better name) : a page summarizes and lists all concepts/tutorials/user scenarios for extensibility.

Let's discuss this part in #5551 please, such changes should be easy to implement after my PR is landed.

My suggested sidebar will look like

I understand the desire to have few key concepts listed in the sidebar under "Inside a LoopBack application". However, I am concerned that such arrangement could cause more harm than good. Consider the current situation, where we have "Key Concepts" and "Behind the scenes" sections - personally, I never know which concept (e.g. Binding vs Controller) belongs to which group and I have always to search both sections to find the docs.

Here is how I see the user experience in my proposed sidebar:

1. As a new user, I read "Overview" to get interested about LoopBack and see why it's a good solution for the kind of a project I am going to build.
2. In the next step, I follow "Getting started" tutorial to get hands-on experience of how does it feel to build LoopBack apps.
3. Now that I like the experience, I read "Inside the LoopBack application" to get a high-level understanding of the basic concepts I need to know about (Controllers, Repositories, etc.)
4. Then I have multiple options how to expand my knowledge: I can try one of the more advanced Tutorials, find solutions for the use cases I need to support in my application ("Usage scenarios") or learn more about the theory in "Behind the scenes". The key idea is that we have clear distinction between tutorials, how-to guides and explanations, so I know where to look for the content I am interested in.

Yes, "Key Concepts" was like a reliable go-to help for the confused souls. Clubbing everything under "Behind the Scenes" is taking away the anchor and adding to the confusion. Also, I am not very convinced by the name "Behind the Scenes".

I agree that we should have an easy way how to find the relevant content and that "Behind the Scenes" may not be the best name.

However, I disagree that "Key Concepts" was a reliable go-to help, because some pages were nested under "Behind the Scenes" section and one had to remember where to find which page. In my proposal, I am solving this problem by bringing all explanations into the same category.

I am happy to use a different name than "Behind the Scenes", do you @hacksparrow have any proposal for a better one?

[bajtos]

Rebased on top of the latest master and addressed review comments in 97c6f71.

@agnes512 @jannyHou @dhmlau @hacksparrow @raymondfeng LGTY now?

Do you have any opinion on git history - can I squash all commits into a single one, or is it better to keep the changes split into multiple commits?

[hacksparrow]

Not able to preview the site locally because of an error:

Liquid Exception: Invalid syntax for include tag: content="A TypeScript limitation prevents mixins from overriding existing members of a base class. Hence the need for // @ts-ignore as shown above. See the API docs for more info."} Now you can extend SimpleController with the two mixins: {% include code-caption.html content="src/controllers/using-mixin.controller.ts" Valid syntax: {% include file.ext param='value' param2='value' %} in pages/Mixin.md

I have a success rate of around 50% with most Ruby-based tools.

Does it still look like this?

IMO, all top level menus should have contents inside them. In fact, "Getting Started" and "Inside a LoopBack Application" should probably go under "Overview".

I am happy to use a different name than "Behind the Scenes", do you @hacksparrow have any proposal for a better one?

"Fundamentals"? As @jannyHou mentioned. Some of the "Behind the scenes" contents ("Key Concepts") could be moved to "Overview".

[dhmlau]

@hacksparrow, there's a missing closing % in Mixin.md. I'll submit a PR for that.

[dhmlau]

@bajtos, I'm good to have this PR land as-is since we will be iterating on it.

Regarding your comments:

• For the "key concepts", actually https://loopback.io/doc/en/lb4/Inside-LoopBack-Application.html#api-implementation is what I was looking for. So it might be good enough.

• For alternative name for "Inside a LoopBack application", if we look at the content, it seems to me:

  • Overview page: "what is LoopBack"
  • Inside a LoopBack application page: "Overview"

• I feel the GDPR page is a bit of an odd-ball. I think it would be better to rework that page to become a How-to guide, something like "Make your application GDPR compliant". WDYT? Such change would be out of scope of this PR though, but I can open a follow-up issue if we think this is something to make happen.

  The name is actually determined by the internal review team across other products. If we want to change it, we probably need to have them look at it again, so I'd prefer to leave it as-is at this point. :) I can also see if I can find the page that suggests where we can put it if it doesn't fit in the Reference section.

• BTW should we create a similar page for California Consumer Privacy Act considerations? Maybe rework the GDPR page into a broader page "Make your app compliant with privacy regulations"?

  If it's not a requirement, perhaps we may not want to add it? There are probably other similar Act in other locations, and I'm not sure if it's realistic to include them all.

• "REST framework"(or a better name) : a page summarizes and lists all REST related concepts/tutorials/user scenarios
  "More than REST"(or a better name) : a page summarizes and lists all concepts/tutorials/user scenarios for extensibility.

  I think it's for the different personas (API developers and extension developers) that @raymondfeng mentioned earlier?

[dhmlau]

LGTM. See my comments: #5718 (comment).

[bajtos]

IMO, all top level menus should have contents inside them. In fact, "Getting Started" and "Inside a LoopBack Application" should probably go under "Overview".

I have different opinion here, see #5718 (comment)

1. As a new user, I read "Overview" to get interested about LoopBack and see why it's a good solution for the kind of a project I am going to build.
2. In the next step, I follow "Getting started" tutorial to get hands-on experience of how does it feel to build LoopBack apps.
3. Now that I like the experience, I read "Inside the LoopBack application" to get a high-level understanding of the basic concepts I need to know about (Controllers, Repositories, etc.)
4. Then I have multiple options how to expand my knowledge: I can try one of the more advanced Tutorials, find solutions for the use cases I need to support in my application ("Usage scenarios") or learn more about the theory in "Behind the scenes". The key idea is that we have clear distinction between tutorials, how-to guides and explanations, so I know where to look for the content I am interested in.

To me, it's fine that some top-level menus don't have any nested content, FAQ is another example.

@hacksparrow feel free to open a follow-up issue to continue this discussion and iterate on the sidebar structure.

I am happy to use a different name than "Behind the Scenes", do you @hacksparrow have any proposal for a better one?

"Fundamentals"? As @jannyHou mentioned. Some of the "Behind the scenes" contents ("Key Concepts") could be moved to "Overview".

I'll open a follow-up issue to continue the discussion about a better name for "Behind the scenes".

I am against moving pages from "Behind the scenes" to other parts (like "Overview"), because it makes those pages more difficult to find for our users and makes it more difficult for us to decide where to put which page. The beauty of four-quadrant documentation system is in the simplicity: if a page is explaining concepts, then it belongs to "Behind the scenes".

For alternative name for "Inside a LoopBack application", if we look at the content, it seems to me:

• Overview page: "what is LoopBack"
• Inside a LoopBack application page: "Overview"

Nice! I'll open a follow-up issue or PR to discuss this further.

[bajtos]

I have created the following follow-up issues & pull requests:

• docs: extract how-to guides from "Server" page docs: extract how-to guides from "Server" page #5768
• docs: move "Reserved binding keys" to "Reference guides" docs: move "Reserved binding keys" to "Reference guides" #5775
• docs: move "Error handling" to "Error codes" in "Reference guides" docs: move "Error handling" to "Error codes" in "Reference guides" #5784
• docs: move "db transactions" to "how-to guides" in sidebar docs: move "db transactions" to "how-to guides" in sidebar #5779
• docs: improve the structure of "Behind the scenes" sidebar + find a better name docs: improve the structure of "Behind the scenes" sidebar + find a better name #5776
• docs: improve the structure of "Usage scenarios" (how-to guides) sidebar docs: improve the structure of "Usage scenarios" (how-to guides) sidebar #5777
• docs: move API references to tsdoc docs: move API references to tsdoc #5778
• docs: move recipes to how-to guides docs: move recipes to how-to guides #5783
• docs: find a better place for "Extending LoopBack 4" in the sidebar [SPIKE] docs: find a better place for "Extending LoopBack 4" in the sidebar [SPIKE] #5785
• docs: untangle connector reference into reference, how-to guides and tutorials docs: untangle connector reference into reference, how-to guides and tutorials #5786
• docs: add a high-level framework overview that's easy to find docs: add a high-level framework overview that's easy to find #5788