How to contribute documentation

[bajtos]

Our current CONTRIBUTING guide is describing the old workflow where all documentation was versioned independently from loopback-next in loopback.io repository. This is no longer true, we keep all LB4 documentation inside loopback-next.

Let's update our CONTRIBUTING guide to accurately describe the process of making documentation changes.

We need to update the current doc-contrib content to make it clear which instructions are applying to LB 3.x and where to find instructions for LB 4.x.

Related tasks:

• Update the contribution page for Loopback 3 Update the contribution page for Loopback 3  #1673
• [Docs] Update ways to contribute to LoopBack [Docs] Update ways to contribute to LoopBack #1228

[dhmlau]

(Looks like we don't have a well-defined acceptance criterion here.)
Reading through the doc-contrib page, it seems to me that there are a lot of content applicable to both (2.x, 3.x) and 4. I'd like to propose the following:

• Under "How LoopBack documentation works" section
  • Add the description about how loopback-next works. i.e. we're copying files from loopback-next to loopback.io to be served in loopback.io, and using master branch
• Under "Agreeing to the CLA"
  • add the loopback-next CLA on top of what we have for loopback.io
• Under "what to work on"
  • add the issues with Docs label in loopback-next repo

Thoughts?

[bajtos]

@dhmlau your proposal looks good to me, I'd like to propose few more steps though:

1. Under "How LoopBack documentation works" section

   Can we also improve the very first sentence to mention that some files are in loopback.io and some in loopback-next?

   LoopBack documentation is sourced in the strongloop/loopback.io GitHub repository, and this site is generated using Jekyll and GitHub pages.

2. Let's improve docs/CONTRIBUTING.md in loopback-next too. At the moment, the section Documentation starts with the following sequence that's no longer accurate:

   LoopBack documentation is sourced in the strongloop/loopback.io GitHub repository.

3. The content in Authoring pages >> Where pages are kept needs an update. The current version creates incorrect impression that lb4 files are sources from loopback.io repository:

   Under English, the sub-folders are:

   • lb2 - LoopBack 2.x
   • lb3 - LoopBack 3.0
   • lb4 - LoopBack 4

4. In Sidebar navigation, explain that lb4_sidebar.yaml is sourced from loopback-next

5. In Including READMEs from other repositories, explain that all READMEs from loopback-next are always fetched together with other doc files. To add a new README to the docs, just create a new page with README layout. This page will be typically created inside loopback-next BTW.

6. Explain how the changes made in loopback-next are propagated to loopback.io, so that people contributing documentation understand when to expect their changes to become live. First, a new version of @loopback/docs must be published to npm. I don't know what happens next - do we have a build pipeline that's triggered to update the files in loopback.io?

[dhmlau]

Explain how the changes made in loopback-next are propagated to loopback.io, so that people contributing documentation understand when to expect their changes to become live. First, a new version of @loopback/docs must be published to npm. I don't know what happens next - do we have a build pipeline that's triggered to update the files in loopback.io?

I thought we're going to add a paragraph describing it under "How LoopBack documentation works"?
@b-admike probably knows what happened next. :) I just know after we published, there's a script got automatically run daily at 3pm EST to see if there's a need to publish. But there's a way to manually trigger it.