Review existing documentation

[dhmlau]

Goal

The goal is to make sure our existing documentation is accurate. Documentation includes loopback.io and READMEs.

Tasks

• review all of the existing documentation for LoopBack 4
• identify problems with the documentation
  • what is out of date?
  • typos
  • grammar mistakes
  • examples that do not compile
  • unclear/confusing examples

Rules

• If you're working on this issue, assign yourself to it (don't remove others!)
• To grab a section:
  • Edit this issue and put your tag next to it
  • Do not claim more than one section at a time
• If the issues you find are trivial to fix, make a PR to fix it (just get it done!)
• If anything requires discussion (not trivial), then make a new issue for it and discuss it there
• Once you've gone over the whole section, mark it complete and grab a new one

Documentation includes:

• Official documentation
  • Installation (@dhmlau)
  • Getting started
    • once this PR https://github.com/strongloop/loopback.io/pull/601/files land, can revisit this page.
  • Key concepts (@shimks)
    • Application (@virkt25)
    • Server (@dhmlau)
    • Context (@shimks)
    • Dependency Injection (@bajtos)
    • Controllers (@shimks)
    • Routes (@shimks)
    • Sequence (@shimks)
    • Model (@dhmlau)
    • Repositories (@shimks)
    • Decorators (@shimks)
  • Using Components (@virkt25)
  • Calling other APIs (@virkt25)
  • Testing your application (@shimks)
  • For current LoopBack users (@shimks)
  • Command-line interface (@dhmlau)
  • Best practices with LoopBack 4 (@shimks)
  • Extending LoopBack 4 (@virkt25)
    • Creating Components
    • Creating Decorators
    • Testing your extension
  • Crafting LoopBack 4 (@dhmlau)
  • Language-related concepts (we're thinking to remove this??) (@shimks)
  • FAQ (@dhmlau)
  • Reference (@dhmlau)
  • Booting an Application (@dhmlau)
• READMEs
  • authentication (@shimks)
  • build (@dhmlau)
  • cli (@dhmlau)
  • context (@virkt25)
  • core (@virkt25)
  • example-getting-started (@kjdelisle)
  • example-hello-world (@dhmlau)
  • example-log-extension (@virkt25)
  • example-rpc-server (@shimks)
  • metadata (@virkt25)
  • openapi-spec-builder(@jannyHou @dhmlau)
    - [ ] openapi-spec
    - [ ] openapi-v2
  • repository-json-schema (@shimks)
  • repository (@shimks)
  • rest (@kjdelisle) (@virkt25)
  • testlab (@dhmlau)
• Example repo: loopback4-example-microservices (@b-admike)

[dhmlau]

• Crafting LoopBack doc: example repo links are out of date.
  • Example for application developer: http://loopback.io/doc/en/lb4/Crafting-LoopBack-4.html#example-for-application-developers
  • Example for extension developer: http://loopback.io/doc/en/lb4/Crafting-LoopBack-4.html#example-for-extension-developers

UPDATED (2/21): those are already fixed

[kjdelisle]

Rejecting

We need to split this up into separate tasks so that we can assign the functional areas/modules to their corresponding experts (since they should be the ones ensuring the documentation is accurate).

For other areas that aren't modules, we should have a separate spike that the team can work on as necessary. EDIT: see below

[jannyHou]

A personal opinion: based on our current progress of upgrading from v2-v3, I would suggest don't spend too much effort on reviewing routing decorator @param since it's going to be refactored soon. Any document change/clarification will be done as part of the upgrade story.

[kjdelisle]

I started creating some of these items as we discussed in the meeting, but in hindsight, it's starting to feel way too bureaucratic and bloated. I'm just going to regroom this PR to make sure it's clear enough regarding expectations instead of making more issues.