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.

[dhmlau]

@kjdelisle , I've added one more item for checking the only standalone example repo loopback4-example-microservices.
According to this PR in that repo, it doesn't seem like the example is working.
cc @b-admike

[kjdelisle]

I don't think this is a spike, given that it involves doing a whole bunch of work to fix things, and only involves creating new issues when complex problems arise.

[dhmlau]

sounds good to me

[virkt25]

@shimks great idea. Done :)

[shimks]

One question that wasn't discussed in the grooming: if a page is deemed outdated and needs a rework, what do we do to the page before creating an issue for the rework? If a code snippet no longer works/compiles, do we:

• fix the code so that it works?
• Or do we slap on a notice saying that the page is outdated and leave it alone?

[virkt25]

Depends on the amount of effort. What page?

That said if it will require significant updates to even make the code work then just make an issue and bring it up for prioritization. If the content itself needs to be updated then go with creating a new issue.

[shimks]

The question rose up while I was looking over Controller.md: it's all about making a controller using the top-down approach (making a spec first instead of having it automatically generated). I think for that page itself, it's fine to do a menial amount of work to make the code work and have an issue to replace the content.

But if you take a look at a giant like Best Practices, it's hard to make these menial code changes to the code snippets when multiple code snippets are building on top of a single outdated concept that's no longer supported.

I guess I answered my first half of the question there though. But for the second part (docs that need overhaul), I guess it's rather specific to the pages. For example, you deemed that Extending-LoopBack needed to be overhauled, but that page probably doesn't have a lot of things that need fixing in terms of making the code work. But for Best-practices-with-LoopBack, that thing is a hard subject to tackle both content-wise and concept-wise.

TLDR; I think it's different for most pages and we should make the judgement call in the issue that we're creating.

[shimks]

@dhmlau I don't recall seeing a PR for openapi-spec-builder README. Has it already been done as part of @jannyHou's work?

[shimks]

Closing as done