docs: menu change current to lb3 #2327

bschrammIBM · 2019-02-01T20:11:14Z

Checklist

npm test passes on your machine
New test dded 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

bschrammIBM · 2019-02-01T20:12:58Z

Changed For current LoopBack users to For LoopBack 3.x users on the menu. Rationale is that Current users now refers to LB4.

raymondfeng · 2019-02-01T21:18:52Z

@bschrammIBM I amended the commit message for you so that CI can pass the check. See https://github.com/strongloop/loopback-next/blob/master/docs/site/DEVELOPING.md#commit-message-guidelines for future references.

bajtos

+1 for the change described at the top.

I am confused about what I see in the patch. What is the purpose of Example1.md file and how is it different from Examples.md? Similarly for Contribution1.md and Contributions.md.

Even more importantly: I am afraid you are making the changes in the wrong place. Documentation for LoopBack version 4 is maintained in loopback-next monorepo.

docs/site/sidebars/lb4_sidebar.yml

docs/site/example_rpc.md

bschrammIBM · 2019-02-05T21:42:11Z

Here is a complete description of these edits. These are tracked in: #2168 and #2087

The sidebar menu selection "For current LoopBack users" was renamed to "For LoopBack 3.x users" - current users are now LB4 users
The Examples and Tutorials category was reorganized into:
Examples and Tutorials

Tutorials
Examples
Contributions from the LoopBack Community

bschrammIBM · 2019-02-05T21:50:48Z

@bajtos Please review the current edits in my branch change_current_lb3.
I am working in the following local repo: /Users/bschramm/loopback-next/docs/site so I think that is correct.

bajtos

Please review the current edits in my branch change_current_lb3.

Done, see my comments below. The first one is important to address, the rest are points to discuss.

I am working in the following local repo: /Users/bschramm/loopback-next/docs/site so I think that is correct.

Yes, you are working correctly. It was me who was confused, I apologize again.

bajtos · 2019-02-07T07:11:53Z

docs/site/Example1.md

+title: Examples
+keywords: LoopBack 4.0
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/Examples.html


I am confused about the purpose of this file. It has filename Example1.md, uses the same permalink /doc/en/lb4/Examples.html as the file Example.md below, and described rpc-server example only.

Maybe this some sort of a back-up or earlier draft that should have been deleted before opening the pull request?

Anyhow, can we remove this file?

Yes I did remove it and somehow it was added back in after my many conflict resolutions! It was an interim file.

bajtos · 2019-02-07T07:22:56Z

docs/site/Examples-and-tutorials.md


 - **[todo](todo-tutorial.md)**: Tutorial on building a simple application with
  LoopBack 4 key concepts using bottom-up approach.

 - **[todo-list](todo-list-tutorial.md)**: Tutorial on introducing related models
  and building their API from the Todo tutorial

+- **[soap-calculator](soap-calculator-tutorial.md)**: Tutorial on integrating
+  SOAP web services.
+- **[hello-world](https://github.com/strongloop/loopback-next/tree/master/examples/hello-world)**:


We are listing all individual tutorials, but then pointing to another page for a list of examples. I would prefer to be more consistent and do the same for tutorials and examples.

In my experience, when the same information is maintained in multiple places (Examples-and-tutorials, Examples, Tutorials), these places eventually get out of sync because people will often make change in one place only and forget about the other places.

I am proposing to trim down Examples-and-tutorials and maintain the list of tutorial inside Tutorials.md only.

Conceptually:

LoopBack 4 comes with tutorials, which are available here: - **[Tutorials](Tutorials.md)** LoopBack 4 also comes with example projects, which are available here: - **[Example Projects](Examples.md)**

Having said that, this deep structure may be less friendly to our readers, they will have to make one more click to find the example/tutorial they are looking for. Two alternatives to consider:

Don't create additional level of nesting. Keep both tutorials & examples in the same sidebar. Use sections in Examples-and-tutorials to split the list in multiple parts - tutorials, examples, contributions.

Leverage {% include %} to keep the list of examples/tutorials in a single file, and render this list on multiple pages (Examples-and-tutorials, Examples, Tutorials). Prior art in LB 3.x docs: Remote Methods and rm-options.md. Personally, I find this setup a bit confusing, because it takes me time to figure out where to locate the included file.

Let's discuss!

/cc @dhmlau @strongloop/sq-lb-apex

You need to decide how important it is to separate Examples and Tutorials. I like the idea of having one page to link to the 3 sections, rather than separate landing pages.

I don't really mind, at first, whether it is Examples and tutorials and having a nested Examples and Tutorials. After a second thought, if we'll be showing the step as the nested item under tutorials, it might be good that we have Examples and Tutorials as the top level element.

For tutorials (if those really fit, see my comment below), i think it makes sense to be consistent to have a similar format as the todo tutorial.

I would like to see:

examples and tutorials list on separate pages

tutorials are kept in docs and example steps are kept in each example repository

The menu structure would be:

Tutorials

Todo: a page with todo tutorials

TodoList: a page with todo list tutorials

...(more tutorials)

Examples: We only need one page to list all available examples without sub menus. And the example repository keeps all the details in its .md file

HI @jannyHou the description in your comment is what the current design is for this PR (except for the Contibutions section which you don't mention, but what you described for Tuts and Ex is what is contained in current PR)

examples and tutorials list on separate pages

tutorials are kept in docs and example steps are kept in each example repository

The menu structure would be:

Tutorials

Todo: a page with todo tutorials

TodoList: a page with todo list tutorials

...(more tutorials)

Examples: We only need one page to list all available examples without sub menus. And the example repository keeps all the details in its .md file

bajtos · 2019-02-07T07:24:36Z

docs/site/Tutorials.md

+LoopBack 4 comes with the following tutorials:
+
+- **[hello-world](https://github.com/strongloop/loopback-next/tree/master/examples/hello-world)**:
+  Tutorial on setting up a simple hello-world application using LoopBack 4.


Are we sure that hello-world is a tutorial? AFAICT, it does not come with any actual tutorial guiding readers through the steps needed to build such application. Should we perhaps move hello-world to Examples section?

I thought it was an example also, but the title said tutorial. I vote yes to move it to Examples.

bajtos · 2019-02-07T07:26:57Z

docs/site/Tutorials.md

+- **[todo-list](todo-list-tutorial.md)**: Tutorial on introducing related models
+  and building their API from the Todo tutorial
+
+- **[log-extension](https://github.com/strongloop/loopback-next/tree/master/examples/log-extension)**:


Should we extract the tutorial part from log-extension's README into a proper tutorial page in our docs?

See https://github.com/strongloop/loopback-next/blob/c268d5a48a7205719c9df0436fd70cd6c6659a1e/examples/log-extension/README.md#tutorial

This is what we have in other tutorial projects, this snippet is cross-posted from examples/todo/README.md:

## Tutorial To follow this tutorial, begin with the [Create your app scaffolding](http://loopback.io/doc/en/lb4/todo-tutorial-scaffolding.html) section

Another point to discuss with @dhmlau @strongloop/sq-lb-apex

It would be good to be consistent with the todo tutorial. However, I'm looking at the README for the log-extension from the above link, it looks more like an example to me? It has some description on the changes, but not really step by step showing how to create an extension.

Thoughts?

Reading log-extension again, @bajtos, you're right that it has some instructions in how to build it, thus fits as tutorial. We can extract the steps to sidebars in this PR or a follow up. I'm good either way.

dhmlau · 2019-02-08T18:03:24Z

@bschrammIBM , thanks for taking up on this! I've added my comment. As @bajtos mentioned, could you please fix the PR so that unwanted files are not here? It will help with the review. Thanks!

jannyHou

Thank you @bschrammIBM Mostly LGTM, I left some comments for the discussions.
(And remember to delete the Example1.md file :-p)

jannyHou · 2019-02-08T19:22:40Z

docs/site/Examples-and-tutorials.md

+
+Projects that were contributed by the LoopBack community are available here:
+
+- **[Contributions from the LoopBack Community](Contributions.md)**


I think we have a contribution page https://loopback.io/doc/en/contrib/index.html, while I also noticed that https://loopback.io/doc/en/lb4/ doesn't have an explicit menu that links to it, at least on the top level menu.
I am not sure is it a good idea to add it to this page...I suggest if we want to add an entry for contributions doc, make it a top level menu that links to https://loopback.io/doc/en/contrib/index.html

I think the goal was to request Tutorials and Examples from the community for the Contributions page. But we can update the https://loopback.io/doc/en/contrib/index.html page to include loopback-next, because for right now it only applies to loopback 3. Ans then link to it. But I thought we wanted a place specifically for Tuts and Ex.

dhmlau · 2019-02-15T02:09:43Z

For posterity, @bschrammIBM and I had a discussion on how to move this PR forward:

Go with the approach mentioned in here. i.e.

Tutorial (root level) - this page contains the list of tutorials listed in the child elements.

Todo tutorial
- step 1 of todo tutorial
- .....
Todo list tutorial
...
Examples (root level) - page that contains a list of examples.
We will omit "examples coming from the community" for now because we basically don't have anything to put.

@bschrammIBM , please correct me if i miss anything. Thanks.

docs: ex and tut menu structure docs: fix sdebar docs: menu change current to lb3

docs: ex and tut menu structure docs: fix sdebar

dhmlau

@bschrammIBM, please see my latest comment. Thanks.

dhmlau · 2019-02-20T14:16:24Z

docs/site/Contributions.md

@@ -0,0 +1,10 @@
+---


I thought we've discussed this will not be included because we don't have anything to put it there?

It was supposed to be removed. Must have been a git error again. I will remove it (again)!

docs/site/Examples.md

dhmlau · 2019-02-20T14:26:39Z

docs/site/Tutorials.md

+- **[todo-list](todo-list-tutorial.md)**: Tutorial on introducing related models
+  and building their API from the Todo tutorial
+
+- **[log-extension](https://github.com/strongloop/loopback-next/tree/master/examples/log-extension)**:


Reading log-extension again, @bajtos, you're right that it has some instructions in how to build it, thus fits as tutorial. We can extract the steps to sidebars in this PR or a follow up. I'm good either way.

docs/site/Examples.md

dhmlau

once this is addressed, LGTM. Thanks!

dhmlau

Thanks @bschrammIBM!

jannyHou

LGTM 👍

bschrammIBM requested review from bajtos and raymondfeng as code owners February 1, 2019 20:11

raymondfeng force-pushed the change_current_lb3 branch from b6a8d9c to 22f976f Compare February 1, 2019 21:18

bajtos suggested changes Feb 5, 2019

View reviewed changes

docs/site/sidebars/lb4_sidebar.yml Outdated Show resolved Hide resolved

docs/site/example_rpc.md Outdated Show resolved Hide resolved

bschrammIBM requested review from hacksparrow and jannyHou as code owners February 5, 2019 22:44

bschrammIBM force-pushed the change_current_lb3 branch 2 times, most recently from f137206 to 4e0cb2c Compare February 6, 2019 16:42

bajtos reviewed Feb 7, 2019

View reviewed changes

jannyHou reviewed Feb 8, 2019

View reviewed changes

bschrammIBM force-pushed the change_current_lb3 branch from 4d24ea2 to 50d005f Compare February 16, 2019 02:34

bschrammIBM added 2 commits February 19, 2019 17:26

docs: menu change current to lb3

5ae649d

docs: ex and tut menu structure docs: fix sdebar docs: menu change current to lb3

docs: remove interim file

9fb3333

docs: ex and tut menu structure docs: fix sdebar

bschrammIBM force-pushed the change_current_lb3 branch from e29ef04 to 9fb3333 Compare February 20, 2019 01:36

dhmlau reviewed Feb 20, 2019

View reviewed changes

bschrammIBM added 3 commits February 21, 2019 13:28

docs: remove Contributions.md

9cdc84f

docs: add hello-world to examples

638ec40

docs: change order of tuts

a9282b6

dhmlau reviewed Feb 22, 2019

View reviewed changes

docs/site/Examples.md Outdated Show resolved Hide resolved

dhmlau reviewed Feb 22, 2019

View reviewed changes

docs: add space to hello-world

da0c055

dhmlau approved these changes Feb 23, 2019

View reviewed changes

jannyHou approved these changes Feb 25, 2019

View reviewed changes

b-admike approved these changes Feb 25, 2019

View reviewed changes

nabdelgadir approved these changes Feb 25, 2019

View reviewed changes

dhmlau merged commit ec0abf4 into master Feb 25, 2019

dhmlau deleted the change_current_lb3 branch February 25, 2019 20:51

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: menu change current to lb3 #2327

docs: menu change current to lb3 #2327

bschrammIBM commented Feb 1, 2019

bschrammIBM commented Feb 1, 2019

raymondfeng commented Feb 1, 2019 •

edited

Loading

bajtos left a comment

bschrammIBM commented Feb 5, 2019 •

edited

Loading

bschrammIBM commented Feb 5, 2019 •

edited

Loading

bajtos left a comment

bajtos Feb 7, 2019

bschrammIBM Feb 7, 2019

bajtos Feb 7, 2019

bschrammIBM Feb 7, 2019

dhmlau Feb 8, 2019

jannyHou Feb 8, 2019

bschrammIBM Feb 11, 2019

bajtos Feb 7, 2019

bschrammIBM Feb 7, 2019

bajtos Feb 7, 2019

bschrammIBM Feb 7, 2019

dhmlau Feb 8, 2019

dhmlau Feb 20, 2019

dhmlau commented Feb 8, 2019

jannyHou left a comment

jannyHou Feb 8, 2019

bschrammIBM Feb 11, 2019

dhmlau commented Feb 15, 2019

dhmlau left a comment

dhmlau Feb 20, 2019

bschrammIBM Feb 20, 2019

dhmlau Feb 20, 2019

dhmlau left a comment

dhmlau left a comment

jannyHou left a comment


		Projects that were contributed by the LoopBack community are available here:

		- [Contributions from the LoopBack Community](Contributions.md)

docs: menu change current to lb3 #2327

docs: menu change current to lb3 #2327

Conversation

bschrammIBM commented Feb 1, 2019

Checklist

bschrammIBM commented Feb 1, 2019

raymondfeng commented Feb 1, 2019 • edited Loading

bajtos left a comment

Choose a reason for hiding this comment

bschrammIBM commented Feb 5, 2019 • edited Loading

bschrammIBM commented Feb 5, 2019 • edited Loading

bajtos 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

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

dhmlau commented Feb 8, 2019

jannyHou left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dhmlau commented Feb 15, 2019

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

dhmlau left a comment

Choose a reason for hiding this comment

dhmlau left a comment

Choose a reason for hiding this comment

jannyHou left a comment

Choose a reason for hiding this comment

raymondfeng commented Feb 1, 2019 •

edited

Loading

bschrammIBM commented Feb 5, 2019 •

edited

Loading

bschrammIBM commented Feb 5, 2019 •

edited

Loading