Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Spike][Docs] reorganize connector reference into reference, how-to guides, and tutorials #6061

Merged
merged 1 commit into from
Aug 16, 2020

Conversation

agnes512
Copy link
Contributor

@agnes512 agnes512 commented Aug 5, 2020

Closes #5961

Suggestion

Currently, our connector reference sits under "Reference Guides". It's hard to find a specific connector page as the path might be Reference Guides/Connector reference/Database Connector/MySQL connector/Tutorial.
Here is a proposal of how to reorganize them into the four quadrants

REFERENCE GUIDES

keep the current connector reference as is.

BEHIND THE SCENES

image

add a section or a subpage under "Behind the scene/Datasource" that talk about:

  • what is connectors
  • what role it plays in req/res cycle, and what relation it has between model and other artifacts (briefly)
  • connector types (add links ):
    • SQL (transaction), NoSQL (freeform properties)
    • Services connectors (service proxy) and others
    • (optional) In-memory connector
    • (optional) Community connector

HOW-TOS

Screen Shot 2020-08-05 at 5 04 01 PM

add a page "Configuring DataSource"(or a better name) under "How-tos/Access Database" that talks about common connector configurations such as:

  • how to configure the connector ( what properties the connector configuration might take
  • how type maps ⚠️ should finish task Add missing LoopBack 4 Types docs Add missing LoopBack 4 Types docs #5063 first
    • to database (Database Migration), e.g String -> Varchar, Boolean -> Tinyint
    • from database (Discovery), e.g Bigint -> int, Text -> String
  • how to customize table/column names
  • how to discover/migration tables/models
  • list connector specific topics, e.g transaction, objectId, and readers should check the corresponding connector pages.
  • add links to connector reference

TUTORIALS

Screen Shot 2020-08-05 at 5 11 19 PM

Add a page "Connect to back-end tutorial" under "Tutorials" that:

  • Briefly introduce what is connectors and what connectors LB provides.
  • List the connector tutorials we have in connector ref (MySQL, PostgreSQL, Oracle, and MongoDB)
  • Add the link to connector ref

@jannyHou
Copy link
Contributor

jannyHou commented Aug 6, 2020

  • "a section or a subpage under Behind the scene/Datasource " 👍
  • "add a page "Configuring DataSource"(or a better name) under How-tos/Access Database" 👍
  • "add a page Connect to back-end tutorial under Tutorials" 👍

The plan LGTM, awesome.

Copy link
Member

@bajtos bajtos left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like the proposal at high level 👏🏻

Let's improve the content users will see when this PR is deployed to loopback.io, see my comments below.

docs/site/Configuring-datasource.md Show resolved Hide resolved
@@ -81,3 +81,17 @@ Attach the newly created datasource to the app by calling `app.dataSource()`.
The `app.datasource()` method is available only on application classes
with `RepositoryMixin` applied.
" %}

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the content above (e.g. "Creating a datasource at runtime") should be eventually moved to "How-to guides" and/or the new page "Configuring-datasource.md" you are creating? I guess that's out of scope of this PR, just want to mention it.

docs/site/DataSources.md Outdated Show resolved Hide resolved
@agnes512 agnes512 merged commit a608aba into master Aug 16, 2020
@agnes512 agnes512 deleted the conn-ref-spike branch August 16, 2020 13:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[Spike] docs: untangle connector reference into reference, how-to guides and tutorials
4 participants