Documentation improvements 2020Q3

[dhmlau]

We'd like to use this issue to capture how we can improve documentation.

From the discussion with @raymondfeng and @bajtos:

Adding new documentation pages

• Add/modify useful LB3 docs to LB4 docs [EPIC] Migrate relevant LB3 docs to LB4 #4848
  • Add "Running and Debugging apps" [EPIC] Add "Running and Debugging app" page #4844
• how to use @loopback/context outside of LB
• how to use @loopback/http-server outside of LB
• how to use @loopback/testlab both inside and outside of LB
• how to build microservice using LoopBack
• What users can do after scaffolding the LB app
  • potentially after the project template will contain the link to this. Related to [CLI] Improve readme of a new project #4981
• Add a page for extensions by the community
  • e.g. https://loopback.io/doc/en/lb3/Community-connectors.html.

Reorganizing the documentation to make content easier to find

• Rework loopback.io navbar
  • possibly find a better place for "GraphQL" and "Test your APIs".
  • possibly add blog, github, slack icons on the top right
  • details to be discussed
• Reorganize sidebar: [Spike] New sidebar for loopback.io #5295
• Hide @loopback/openapi-v3 from docs, examples and CLI templates Hide @loopback/openapi-v3 from docs, examples and CLI templates #5692

Adopt the four-quandrant documentation system

• 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

Related: #4717

[dhmlau]

@achrinza, would like to get your inputs on this. Thanks.

[achrinza]

I think this is a great idea, and would possibly help users better find the information they're looking for. It'll also make the responsibilities of each LoopBack package clearer.

To add on, I think there's 2 main, overreaching user stories that we need the docs to cater towards:

1. I want to create an API using LoopBack 4

2. I want to use individual LoopBack 4 components (in an existing application)

So it may be a good idea to separate the docs as such.

To make it even clearer, the Overview page should show the users these 2 options and redirect them to the correct sections of the docs.

Both of these user stories want to reap some common benefits of LoopBack 4:

1. High extensibility
2. Reduced time to market
3. Maintainability

These separate docs may have an overlap of information, but they would cater more specifically towards their user story. For example, for the 2nd user story, the docs would be grouped based on the individual Node.js packages, with examples that can be used in isolation without the other LoopBack packages.

As another discussion point: I'm wondering if we should create a separate sidebar for the 2nd user story, as the current sidebar is quite cluttered as-is.

[dhmlau]

In the discussion with @raymondfeng and @bajtos, @raymondfeng also suggested to look in the different personas and different stage of the application development cycle (development, testing, deployment).

On that front, I was trying to capture the documentation pages that I might need to look up as a user when i'm trying to create my own app. Here is the working-in-progress version: https://github.com/dhmlau/learning-loopback/blob/master/loopback-for-beginners.md.

I agree that our current sidebar is already quite cluttered. I'm thinking whether it's better to have separate "user/developer guide", "deployment guide", etc, would be a good solution.

[achrinza]

Thanks for the link @dhmlau, I'll feedback where possible.

Just throwing it into the discussion - I think it may help new users greatly if we can break down the docs by the lifecycle of a LoopBack application:

1. Understanding (the core concepts of LoopBack)
2. Developing
3. Testing
4. Debugging
5. Deploying

Right now, our docs are leaning heavily towards the "Developing" part of the lifecycle, and the rest (especially testing) are more of an afterthought.

By creating these well-defined sections in the docs, we can achieve 2 things:

1. Make the docs easier to navigate
   The docs are currently a combination of these cycles with no clear boundaries. Some "Testing" docs are under the "Best Practice" section, while others are hidden and scattered in other parts of the docs.
2. Formalize the location of the different types of docs
   Currently, there isn't much of a formal guide on where the "testing" or "scaffolding" portion of the docs should be located at. By defining these sections, we can clearly decide on where to put certain content.

These sections can be repeated for the package-specific docs too so that they can benefit from the same segmentation.

[achrinza]

Quoting from #5104 (comment):

I understand its a very difficult task to explain how works Authentication and Authorization with all these interfaces, providers, services, ... to implements.

If we can create an "Understanding" section, we can have an opportunity to tell users a story on the different core components of LoopBack 4 and their purpose, without needing to go into details of the implementation. Think of it like a low-altitude flight of these concepts.

This will allow users to build up their knowledge on the underlying fundamentals that LoopBack is built on top of.

[mdbetancourt]

Has anyone seen the documentation of rxjs? https://rxjs-dev.firebaseapp.com/guide/overview is beautiful I think loopback is a beautiful framework but it fails in the documentation, and i never saw something like this before https://rxjs-dev.firebaseapp.com/operator-decision-tree so cool

[dhmlau]

If we can create an "Understanding" section, we can have an opportunity to tell users a story on the different core components of LoopBack 4 and their purpose, without needing to go into details of the implementation. Think of it like a low-altitude flight of these concepts.

@achrinza, Your comment is spot on! I think the separation of "how to use it" and "let me explain how it works" is important.

@mdbetancourt, thanks for the link. Let me take a closer look. I like the API list: https://rxjs-dev.firebaseapp.com/api. :)

[achrinza]

Not too sure if it's out-of-scope, but I think it's worth mentioning for reference (since we're doing a rather major docs refactoring):

We may benefit from redesigning the architecture from Jekyll to Gatsby.js.

Here's why:

• Create more modular and maintainable pages with React.js
• Move towards an "all Node.js" infra so that it's easier to contribute and extend for others

There's some downsides that I can see:

• It'll take time to re-architect development
• We'll also need to re-architect deployment to work around the constraints of GitHub Pages

[mdbetancourt]

@achrinza
I just wanted to recommend that, that type of documentation is also easier to navigate and you can even install it as an app and have it without internet access.

On my part i recommend:

• https://gridsome.org/ a great tool (like gatsby) or
• https://vuepress.vuejs.org/guide/ more simple

[bajtos]

Great discussion 👏

Let me add few more thoughts.

To add on, I think there's 2 main, overreaching user stories that we need the docs to cater towards:

1. I want to create an API using LoopBack 4
2. I want to use individual LoopBack 4 components (in an existing application)

As part of thinking about these two stories, I think it's important to identify different ways how developers are going to discover LoopBack packages and features.

For the first story, the user is already interested in LoopBack 4, so I would expect they start looking in our documentation.

For the second story, many users won't be aware of LoopBack at all, they will be searching the internet (perhaps npmjs.org) for a solution to their problem. Quite often, they will not care if a package like @loopback/http-server is a part of a larger framework, all they are looking for is docs showing how to solve their specific problem.

I think we should create a new microsite for each package that's intended to be used outside of LoopBack. When I say microsite, I don't necessarily mean a full web site like https://loopback.io. A microsite can have different forms, depending on how much docs we need to write.

1. For small packages like @loopback/http-server and @loopback/testlab, it's probably best to put all documentation into the main README file. This way the documentation is mirrored at npmjs.org, which makes it very easy & fast for potential users to assess what features the package offers and how easy the API is to use. The README is the microsite.

2. For larger packages, especially @loopback/context, we can create a new section (a new sidebar) on our main documentation site. IMO, there should be a dedicated sidebar for each package. This dedicated section of our docs is the microsite. The README file of a package with a dedicated docs microsite can be much shorter - provide enough teasers to make readers interested and then point them to loobpack.io docs to learn more.

   This is pretty much the same as what @achrinza wrote:

   As another discussion point: I'm wondering if we should create a separate sidebar for the 2nd user story, as the current sidebar is quite cluttered as-is.

We may benefit from redesigning the architecture from Jekyll to Gatsby.js.

Regarding switching from Jekyll to something else: we have already explored migration to VuePress in the past - see strongloop/v4.loopback.io#45, but decided to keep using Jekyll.

I am often frustrated by Jekyll's long build times, it would be great to find a faster tool. It would be even better if the tool was able to source the doc files from different GitHub repositories and the npmjs.org registry, so that we don't have to run a CI/CD job to unpack every new version of @loopback/docs and commit it to loopback.io git history.

Having said that, such change looks like a non-trivial project to me, I don't know if it is the right task to spend our precious time now 🤷