docs: add a new section on content organization #5659

bajtos · 2020-06-04T12:25:33Z

Based on the discussion in #5550, I am updating the documentation for developers with the definition of "building-blocks", a list of packages considered as building blocks, and finally instructions on how to treat these packages in our docs, CLI templates and examples.

After this PR is approved, I'll created follow-up stories to ensure proper use of the following packages:

packages/context - already done in chore: use @loopback/core for packages consistently #5625
packages/express - see Hide @loopback/express from framework-level documentation #5693
packages/metadata - see Hide @loopback/metadata from framework-level documentation #5696
packages/openapi-v3 - see Hide @loopback/openapi-v3 from docs, examples and CLI templates #5692

The following packages are already not exposed:

packages/http-server
packages/repository-json-schema

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 · 2020-06-04T12:27:04Z

Please note this PR is just a small incremental step on a longer journey, I expect us to do more doc-related improvement in follow-up stories and pull requests, depending on how the discussions in #5113, #5550 and #5549 evolve.

hacksparrow · 2020-06-04T13:09:46Z

docs/site/DEVELOPING.md

+package should be moved to "building blocks" and our documentation should be
+updated to reference the higher-level "framework" instead.
+
+List of packages that are considered as building blocks:


And the rest are framework-level pacakges? If yes, we should mention that, else it feels like the list of framework-level pacakges is missing.

Done in 69dcaa6

There is one thing that bugs me a bit: we also have utility packages like @loopback/build or @loopback/testlab that are technically not part of the framework, but they are not building blocks either in the sense that they should be mentioned in our framework documentation.

I guess "framework-level" is not the best term to use. Can we come up with a more accurate name?

What about the extensions and examples packages? Those seem more like an adds-on.

What about the extensions and examples packages? Those seem more like an adds-on.

Sure 👍

What I am trying to accomplish here is to distinguish between "building blocks" packages that should not be referred to in our docs, CLI templates and example apps; and everything else.

I used the term "framework-level" for "everything else", which is clearly misleading based on your feedback.

So, what would be a better term?

I guess "framework-level" is not the best term to use. Can we come up with a more accurate name?

They need not belong in the framework packages. They can be classified as helper/utility packages.

I am adding the following clarification to the docs:

#### Framework-level packages All packages not listed above are considered as framework-level. We consider utilities like `@loopback/testlab` and example projects like `@loopback/todo` as framework-level too.

We consider utilities like @loopback/testlab and example projects like
@loopback/todo as framework-level too.

Doesn't feel right. Anything that LoopBack developers would not (maybe even never) use in their project feels very odd to be classified under framework-level packages. We need a third category - helpers, utility, along that line.

I guess this is subjective.

Let's land my PR as the first step, and then you can open a follow-up PR to discuss how to improve this initial categorization.

Sounds good.

raymondfeng · 2020-06-04T20:38:04Z

docs/site/DEVELOPING.md

+groups:
+
+1. Building-blocks are lower-level packages that are typically not consumed by
+   LoopBack projects directly, instead there is a higher-level package exposing


LoopBack projects -> LoopBack applications or LoopBack application projects.

Well, I think this applies to most extension projects too, but let's not dwell on details. I am going to use "LoopBack applications" for now, we can improve this later as we get a better picture about the documentation for extension authors.

raymondfeng · 2020-06-04T20:48:39Z

docs/site/DEVELOPING.md

+writing docs. While this is good for capturing the knowledge in a text form, it
+also makes the documentation difficult to follow by people new to LoopBack.
+Newcomers get quickly overwhelmed by the amount of concepts they need to
+understand and all the different packages they need to know about.


We should also mention the balance between modular design and ease of use.

Module design leads to great flexibility and composability. As the number of modules grows, it also increases the complexity as developers need to know what to choose and how to use.

We need to target high-level packages for application developers without dragging in lower-level details.

We may want to identify several personas of different interest/entry to LB here:

Platform/extension developers

Application developers

We may want to identify several personas of different interest/entry to LB here:

Platform/extension developers

Application developers

Yeah, I agree that at some point, we need to step back and reorganize our docs to cater for different personas. As I see it, our current docs is mostly aimed at application developers. In this pull request, I am proposing how to make the docs easier to read for app developers. We can discuss how to better address other personas in #5113.

raymondfeng · 2020-06-04T20:49:15Z

docs/site/DEVELOPING.md

+To prevent that issue, we have categorized all monorepo packages into two
+groups:
+
+1. Building-blocks are lower-level packages that are typically not consumed by


not consumed -> not directly consumed or not explicitly consumed?

I wonder if we can find a better name for building blocks. Maybe foundation-level packages to be symmetric with framework-level?

Or library-level?

not consumed -> not directly consumed or not explicitly consumed?

English is not my mother tongue, but I believe that my current version is grammatically correct while conveying the same meaning.

lower-level packages that are typically not consumed by LoopBack projects directly

I wonder if we can find a better name for building blocks. Maybe foundation-level packages to be symmetric with framework-level?

I like "foundation-level" + "framework-level".

In #5659 (comment), we were discussing with @hacksparrow that "framework-level" may not be the best description. However, I think with building blocks renamed to "foundation-level", the term "framework-level" is ok.

bajtos · 2020-06-08T08:16:14Z

@hacksparrow @dhmlau @raymondfeng thank you for the suggestions. I rewrote most of the new content to incorporate your feedback, does the new version LGTY now?

hacksparrow · 2020-06-08T11:01:52Z

How do we handle "breaking changes" in docs organization? For example a framework-level package underwent some refactoring and ended up becoming a foundation-level package.

bajtos · 2020-06-08T12:34:21Z

How do we handle "breaking changes" in docs organization? For example a framework-level package underwent some refactoring and ended up becoming a foundation-level package.

At the moment, we have a single version of docs only ("the latest").

I think we will eventually need to introduce versioning (e.g. docs for @loopback/rest version from 2020 vs. version from 2021`), especially once we introduce LTS versions (see #4398). Perhaps such versioning would help?

In the current state, where there is a single version of docs only: When a framework-level package becomes foundation-level, I am envisioning the following process:

docs, CLI templates, example apps are updated to use framework-level APIs instead of referring to he package that was moved to foundation-level
if & where appropriate, we may add additional sections to explain how to migrate from the "old" to the "new" style - see e.g. https://loopback.io/doc/en/lb4/DataSource-generator.html#legacy-json-based-configuration

Is there any specific concern you have, @hacksparrow?

hacksparrow · 2020-06-08T12:57:07Z

My concern was looking at outdated references. Versioning should help.

docs, CLI templates, example apps are updated to use framework-level APIs instead of referring to he package that was moved to foundation-level
if & where appropriate, we may add additional sections to explain how to migrate from the "old" to the "new" style - see e.g. https://loopback.io/doc/en/lb4/DataSource-generator.html#legacy-json-based-configuration

Sounds good for now.

dhmlau

LGTM.

raymondfeng · 2020-06-08T22:17:46Z

docs/site/DEVELOPING.md

+- [packages/http-server](https://github.com/strongloop/loopback-next/tree/master/packages/http-server)
+- [packages/metadata](https://github.com/strongloop/loopback-next/tree/master/packages/metadata)
+- [packages/openapi-v3](https://github.com/strongloop/loopback-next/tree/master/packages/openapi-v3)
+- [packages/repository-json-schema](https://github.com/strongloop/loopback-next/tree/master/packages/repository-json-schema)


This package depends on @loopback/core and @loopback/repository. It should be moved out.

This package depends on @loopback/core and @loopback/repository. It should be moved out.

Please note the criteria is not whether a package depends on something else from @loopback/* namespace, but whether LB application developers should depend on that package directly.

Both @loopback/repository-json-schema and @loopback/openapi-v3 are not meant to be used directly. They are building blocks used by @loopback/rest. Applications are importing their APIs and functionality from @loopback/rest, as can be seen e.g. in examples/todo/src/controllers/todo.controller.ts

raymondfeng · 2020-06-08T22:19:20Z

docs/site/DEVELOPING.md

+- [packages/express](https://github.com/strongloop/loopback-next/tree/master/packages/express)
+- [packages/http-server](https://github.com/strongloop/loopback-next/tree/master/packages/http-server)
+- [packages/metadata](https://github.com/strongloop/loopback-next/tree/master/packages/metadata)
+- [packages/openapi-v3](https://github.com/strongloop/loopback-next/tree/master/packages/openapi-v3)


Not sure about this one either:

"dependencies": { "@loopback/core": "^2.7.1", "@loopback/repository-json-schema": "^2.4.3", }

Signed-off-by: Miroslav Bajtoš <[email protected]>

bajtos added the Docs label Jun 4, 2020

bajtos requested review from raymondfeng, dhmlau and a team June 4, 2020 12:25

bajtos self-assigned this Jun 4, 2020

hacksparrow reviewed Jun 4, 2020

View reviewed changes

raymondfeng reviewed Jun 4, 2020

View reviewed changes

bajtos force-pushed the docs/package-layers branch from 69dcaa6 to 8368999 Compare June 8, 2020 08:15

bajtos requested review from raymondfeng and hacksparrow June 8, 2020 08:16

dhmlau approved these changes Jun 8, 2020

View reviewed changes

hacksparrow approved these changes Jun 8, 2020

View reviewed changes

raymondfeng reviewed Jun 8, 2020

View reviewed changes

docs: add a new section on content organization

76c218d

Signed-off-by: Miroslav Bajtoš <[email protected]>

bajtos force-pushed the docs/package-layers branch from 8368999 to 76c218d Compare June 9, 2020 06:49

bajtos merged commit 394f25a into master Jun 9, 2020

bajtos deleted the docs/package-layers branch June 9, 2020 07:08

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add a new section on content organization #5659

docs: add a new section on content organization #5659

bajtos commented Jun 4, 2020 •

edited

Loading

bajtos commented Jun 4, 2020 •

edited

Loading

hacksparrow Jun 4, 2020

bajtos Jun 4, 2020

dhmlau Jun 4, 2020

bajtos Jun 4, 2020

hacksparrow Jun 4, 2020

bajtos Jun 8, 2020 •

edited

Loading

hacksparrow Jun 8, 2020

bajtos Jun 8, 2020

hacksparrow Jun 8, 2020

raymondfeng Jun 4, 2020

bajtos Jun 8, 2020

raymondfeng Jun 4, 2020

raymondfeng Jun 4, 2020

bajtos Jun 8, 2020

raymondfeng Jun 4, 2020

raymondfeng Jun 4, 2020

raymondfeng Jun 4, 2020

bajtos Jun 8, 2020

bajtos Jun 8, 2020

bajtos commented Jun 8, 2020

hacksparrow commented Jun 8, 2020

bajtos commented Jun 8, 2020 •

edited

Loading

hacksparrow commented Jun 8, 2020

dhmlau left a comment

raymondfeng Jun 8, 2020

bajtos Jun 9, 2020

raymondfeng Jun 8, 2020

docs: add a new section on content organization #5659

docs: add a new section on content organization #5659

Conversation

bajtos commented Jun 4, 2020 • edited Loading

Checklist

bajtos commented Jun 4, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bajtos Jun 8, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bajtos commented Jun 8, 2020

hacksparrow commented Jun 8, 2020

bajtos commented Jun 8, 2020 • edited Loading

hacksparrow commented Jun 8, 2020

dhmlau left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bajtos commented Jun 4, 2020 •

edited

Loading

bajtos commented Jun 4, 2020 •

edited

Loading

bajtos Jun 8, 2020 •

edited

Loading

bajtos commented Jun 8, 2020 •

edited

Loading