docs: improve the structure of "Behind the scenes" sidebar + find a better name

[bajtos]

At the moment, "Behind the scenes" contains a list of topics in a seemingly random order.

Let's find a better organization of the items in this list.

Ideas to consider:

• Sort the entries from A to Z, possibly keeping "Crafting LoopBack 4" at the top

• Reorganize the entries into subsection aligned around different usage scenarios or architecture layer they belong to: Build REST APIs, Access databases, Access existing services, Authentication/authorization, Cloud native, Dependency Injection & IoC, etc.

• Quoting [docs] Adopt four-quadrant documentation system #5718 (comment):

  Maybe we should use a consistent order from top to bottom, from left to right? For example:

  Application/Component/Context/Binding
  Server/Sequence/Action/Route/Controller/Repository/Service/Model/Relation/DataSource

We should update the contents of "Behind-the-scene.md" accordingly too.

See also:

• Improve the structure of "Usage scenarios" (how-to guides) sidebar docs: improve the structure of "Usage scenarios" (how-to guides) sidebar #5777

While we are discussing "Behind the scenes", let's try to find a better name for this section too (see the discussion in #5718 for more details).

This story is a part of #5113 Documentation improvements 2020Q3

Acceptance criteria

• categorize concepts into subsections by responsiblities
• reorganize entires in Behind-the-scene.md as well

[jannyHou]

Given the discussions above, I tested with several plans:

Rename "Behind the scene"

The preview is pretty straightforward, just a name change.

Choice 1: rename to "Concepts"

Choice 2: rename to "Fundamental"

Reorganize items

(Personal opinion: New plans are much better than the current layout. I don't get lost for either of them.)

Alphabetical

List items from a-->z. (Personal opinion: Good when have less items.)

Subsections

Organize by categories. (Personal opinion: Good when have large number of items.)

fold subsections

unfold subsections - part1

unfold subsections - part2

DISCUSSION

Let's first discuss and agree on the choices:

• Rename "Behind the scene"

  • choice 1: "Concepts"
  • choice 2: "Fundamental"
  • others

• Reorganize items

  • choice 1: alphabet. next steps:
    • update the list on page "Behind the scene" with the same sequence
  • choice 2: subsections by category. next steps:
    • agree on the details: the sections in the picture is just a proposal, team can come up with different plans.
    • update page "Behind the scene" and create pages for each subsections.
  • others
    • (I found the 3rd choice confused, cc @bajtos @raymondfeng could you explain more about it? Thanks!)

      Quoting [docs] Adopt four-quadrant documentation system #5718 (comment):
      Maybe we should use a consistent order from top to bottom, from left to right? For example:
      Application/Component/Context/Binding
      Server/Sequence/Action/Route/Controller/Repository/Service/Model/Relation/DataSource

cc @strongloop/loopback-ibmers May I get more reviews and opinions about your preferences? 🙇‍♀️

[agnes512]

Thanks for kicking it off! I like the name "Concepts". As for organization, I think subsections by category with alphabetical order is better in the matter of navigation.

[raymondfeng]

1. I vote for Concepts or Architectural Concepts

2. I would like to see categories as subtitles for concepts

• Core

  • Application
  • Component
  • Context
  • Binding
  • Dependency Injection
  • Interceptor
  • Life cycle event and observer
  • Service
  • Booter

• REST API

  • Server
  • Sequence
  • Middleware
  • Route
  • Controller
  • Request/response cycle

• Data access

  • Model
  • Relation
  • Repository
  • DataSource
  • Connector

• TypeScript

  • Decorator
  • Mixin

3. We should uniformly use singular or plural terms, such as Model vs. Models.

[hacksparrow]

I like the name "Concepts". As for organization, I think subsections by category with alphabetical order is better in the matter of navigation.

Exactly.

[bajtos]

Thank you @jannyHou for the screenshots of different versions, they make it easier to compare different proposals 👏🏻

Regarding the new name: the purpose of this section is to explain concepts. Quoting from https://documentation.divio.com/explanation/:

Explanation, or discussions, clarify and illuminate a particular topic. They broaden the documentation’s coverage of a topic.

I feel the name "fundamentals" is too narrow, we want to include information for non-fundamental topics too.

The name "Concepts" looks reasonable to me 👍🏻 Maybe "Concepts & explanations" would be even better?

As for organization of the pages, I vote for category-based subsections containing pages in alphabetical order. A picture from your proposal that I like:

I don't have a strong opinion on how to organize individual pages, I am fine to adopt Raymond's proposal from #5776 (comment).

[jannyHou]

Great so we all like the following plan:

• name "Concepts" (options: "Architecture Concepts" and "Concepts & Explanations")
• order: "subsections by category with alphabetical order"

Thanks everyone, PR coming

[jannyHou]

Related PR merged, closing