docs(lb4): reorganize current tutorial materials #601

kjdelisle · 2018-02-01T22:20:56Z

connected to loopbackio/loopback-next#729

This is a rework of the existing tutorial materials and layout
that uses the example-getting-started materials as a starting
point for new users.

THIS IS STILL A WORK-IN-PROGRESS!
Feel free to review it anyway. :)

kjdelisle · 2018-02-01T22:30:52Z

Right now, the big problem I see with this tutorial is that developers will need a REST client to test it out because we don't bundle a front-end with it.

However, we pulled the static file server from the MVP, so I'm alright with keeping the tutorial as a back-end only affair for now, with a view to using a front-end in the tutorial before we release.

shimks

Haven't taken a detailed look, but is there a for us to see the diff between this and the README in the package itself? Also, do we know of a way somehow keep the tutorial updated as further updates are made to the example-getting-started repo? What I'm afraid of is that we'll always forget to update this page as changes to the example-getting-started packages are made.

shimks · 2018-02-05T18:36:05Z

pages/en/lb4/readmes/example-getting-started.md

+import {PingController} from './controllers/ping-controller';
+import {Class, Repository, RepositoryMixin} from '@loopback/repository';
+
+export class TodoApplication extends RepositoryMixin(Application) {


Could you please refactor the tutorial to use RestApplication? Refer to the latest master branch for consistency.

I've updated the README in this PR loopbackio/loopback-next#961, so you can just copy paste the diffs

shimks · 2018-02-05T18:44:27Z

pages/en/lb4/readmes/example-getting-started.md

+import {db} from './datasources/db.datasource';
+import {TodoRepository} from './repositories';
+
+export class TodoApplication extends RepositoryMixin(Application) {


Same as above

bajtos · 2018-02-06T08:17:50Z

_data/sidebars/lb4_sidebar.yml

-  - title: 'Examples and tutorials'
-    url: Examples-and-tutorials.html
+  - title: 'More examples and tutorials'
+    url: More-examples-and-tutorials.html


This will break any pages referring to the old URL /More-examples-and-tutorials.html. Can we preserve the old URL please?

My reason for renaming this URL is that preserving the current name makes for some confusing UX.
The navbar ends up looking like this:

+ Tutorial + Examples and Tutorials

If we're going to separate them to distinguish between our default introductory tutorial and our other resources, we should make sure there's no confusion about what is what.

What if we rename the route to something like "Additional Learning"?

What about other examples and tutorials?
Or rename the Tutorial to something else? e.g. step-by-step tutorial?

IMO, the URL does not necessarily have to be the same as the page title, e.g. we can have "More examples and tutorials" at lb4/Examples-and-tutorials.html. Although I agree it's better when they match each other.

The reason why I am concerned about this change is that my upcoming blog post is referring to Examples-and-tutorials.html URL and I'd rather avoid synchronization between landing my PR adding the blog post and this PR breaking old URLs.

On the second thought, I think we should simply leverage jekyll-redirect-from plugin that's already configured for loopback.io and add redirect from Examples-and-tutorials.html to More-examples-and-tutorials.html.

How about making Examples and Tutorials a top level item listing all examples / tutorials including the Garden Path tutorial ... and under it the first item can be the Garden Path Tutorial. We can link directly to the Tutorial page from Getting-Started?

bajtos · 2018-02-06T08:21:25Z

pages/en/lb4/readmes/example-getting-started.md

@@ -0,0 +1,424 @@
+## Making A Todo App


I believe the files in readmes are automatically fetched from GitHub, see http://loopback.io/doc/en/contrib/Including-READMEs.html and https://github.com/strongloop/loopback.io/blob/e26a44be2e910740a4eaea2927845b46812a2fd1/update-v4-readmes.sh.

IMO, you need to make these changes in our main monorepo - https://github.com/strongloop/loopback-next/blob/a2368cee598c131a826ee42e347266c6e25ae582/packages/example-getting-started/README.md

If you don't want this content to be fetched from example-getting-started's README, then please put the content to a different file.

Unless I am missing something here?

I'm not exactly sure how it's supposed to work, but I know that the current template we use for transplanting the READMEs into the documents is currently hardcoded to path towards strongloop/{repo-name}, which won't work for our use-case. It looks like we're refreshing those doc pages by committing the updates here rather than scraping them dynamically, since we have a whole folder full of READMEs for those connectors in the loopback.io repository: https://github.com/strongloop/loopback.io/tree/gh-pages/pages/en/lb3/readmes

Sidenote: It also looks like many of them haven't been updated in forever; was this script run manually by Rand or someone else on a regular basis?

Regardless, I wouldn't expect there to already be something in place that copies READMEs over from lb4, and until there is, we need to make sure that there's something in place here.

Quick addendum: I do think that figuring out an automatic refresh of these documents falls within MVP scope, but only if everyone agrees:

@bajtos @raymondfeng @dhmlau

I remember some of the READMEs in LB3 got copied over to the official documentation. Not sure how easy/difficult to do that. Perhaps @bschrammIBM can help us?

We are already fetching some READMEs from loopback-next repository, see #588 for an example how to do that, and also Raymond's recent PR #608 that's fixing some aspects of this process.

Sidenote: It also looks like many of them haven't been updated in forever; was this script run manually by Rand or someone else on a regular basis?

I believe there is a Jenkins pipeline (see Jenkinsfile in this repo) that is supposed to update README whenever they change. I think it's based on some GitHub web hooks, but I am not sure. @rmg could you please clarify?

Regardless, I wouldn't expect there to already be something in place that copies READMEs over from lb4, and until there is, we need to make sure that there's something in place here.

Uff, I am don't understand, could you please rephrase your sentence for more clarity?

Since we already have some tooling for including READMEs from loopback-next packages, I think we should leverage it for your work too, even if this process has flaws right now. At worst, you can run update-v4-readmes.sh manually to ensure the copy of example-getting-started's README is stored in this repo.

If you disagree and think this is more work that we want to invest for MVP, then please apply the second approach I proposed:

If you don't want this content to be fetched from example-getting-started's README, then please put the content to a different file.

I really don't want to create a situation when it looks like pages/en/lb4/readmes/example-getting-started.md is something that's supposed to be automatically mirroring content of example-getting-started/README.md, while it is not a mirror but a completely different content instead.

dhmlau · 2018-02-07T19:02:39Z

_data/sidebars/lb4_sidebar.yml

  url: Installation.html
  output: 'web, pdf'

- title: 'Getting started'


Are we removing the Getting Started? I kind of like it though.
The garden path tutorial might be able to guide people through. But the Getting Started can at least quickly show what LB can do?

Not sure what you're planning for the tutorial. If it's simple enough for people to "Get started", i'm good with removing the getting started.

+1 to keeping Getting started as the page describing the process of ensure Node 8 + TypeScript is installed (does this need to be installed?), installing the CLI, and creating an app (Just show the built-in ping controller). A bare bones, I made a thing with LB4.

Tutorial imo then should go into a more complex app.

I think the Getting Started page can / should fold in the installation page.

ah. just realize @virkt25 has the same comment! :)
see loopbackio/loopback-next#1004

dhmlau · 2018-02-07T19:05:24Z

_data/sidebars/lb4_sidebar.yml

-  - title: 'Examples and tutorials'
-    url: Examples-and-tutorials.html
+  - title: 'More examples and tutorials'
+    url: More-examples-and-tutorials.html


What about other examples and tutorials?
Or rename the Tutorial to something else? e.g. step-by-step tutorial?

dhmlau · 2018-02-07T19:07:09Z

pages/en/lb4/readmes/example-getting-started.md

@@ -0,0 +1,424 @@
+## Making A Todo App


I remember some of the READMEs in LB3 got copied over to the official documentation. Not sure how easy/difficult to do that. Perhaps @bschrammIBM can help us?

dhmlau · 2018-02-07T19:07:41Z

pages/en/lb4/readmes/example-getting-started.md

+
+Before we can begin, you'll need to make sure you have some things installed:
+
+* [Node.js](https://nodejs.org/en/) at v6.x or greater


If we're dropping Node 6, it would be v8 or higher?

virkt25 · 2018-02-08T15:16:11Z

pages/en/lb4/Examples-and-tutorials.md

-  Tutorial on building a simple application with LoopBack 4 key concepts.
-
- **[log-extension](https://github.com/strongloop/loopback-next/tree/master/packages/example-log-extension)**:
+* **[log-extension](https://github.com/strongloop/loopback-next/tree/master/packages/example-log-extension)**:


Can we add headers for each one showing what the tutorial is for. ## Application, ## Extensions, ## Servers

This is a rework of the existing tutorial materials and layout. - Reorganize the current content under the "Examples and tutorials" section - Migrate all of the existing tutorials underneath this section - More clearly separate the "hello world" and "getting started" tutorials by renaming them and linking accordingly - Make use of the existing getting-started readme for the garden path tutorial

kjdelisle · 2018-02-13T19:06:35Z

The issue I have with the "Getting Started" section is that it conflicts with the example-getting-started package, which is not a "Hello World" example, but rather a full application tutorial.

IMO, we have two options:
Option A

Rename the entire example-getting-started package to something like example-todo
Use the "Getting Started" section as the introduction to installation AND the "Hello World" tutorial (how it's currently written without this PR's changes)
Add a new section under the "Examples and Tutorials" header for the new todo tutorial (with auto-updated example linkup)

Option B

Keep the example-getting-started package as it is
Rename the "Getting Started" section to "Hello World"
Have a new and separate "Getting Started" section immediately afterwards that is the full application tutorial.

I'm heavily leaning towards Option A in this case, even though it's a considerably larger effort because it:

Allows us to keep the useful "Getting Started" wording for the actual idea of...you know...getting started.
Makes it clearer what the example package in question actually does (it's a Todo app!)

Option B's obvious advantage is that we don't need to refactor code, but I think it isn't as clear as we'd like it to be and clarity should be our primary goal with any sort of tutorials or documentation!

shimks · 2018-02-13T19:39:56Z

I'm for option 1 as well, reason being that the naming convention would actually reflect the repositories' purposes with that option.

Additionally, I'm thinking that we rename the repo to example-tutorial to make it clear even in the github that it's meant to be THE tutorial. I'm also thinking that the docs for example-getting-started should have their titles changed to to have the word 'tutorial' in them to really hammer in the point that THIS section is THE TUTORIAL

virkt25 · 2018-02-13T20:05:42Z

+1 for Option A

raymondfeng · 2018-02-13T20:41:55Z

+1 to rename example-getting-started to example-todo. The term getting-started is much more opinionated and it should be tied to the name of our examples.

dhmlau · 2018-02-13T20:48:21Z

+1 on renaming and Getting Started content.

Add a new section under the "Examples and Tutorials" header for the new todo tutorial

Is the new todo tutorial the garden path tutorials? because i'm wondering what's so special of that tutorial that we need to make a new section instead of putting it on the same page.

bajtos · 2018-02-14T07:05:35Z

I don't have a strong opinion, I am happy to follow the crowd.

kjdelisle · 2018-02-15T17:48:26Z

Once loopbackio/loopback-next#1001 lands, I'll be able to refactor this PR to include the documentation from that package as individual pieces, and then wrap that content with appropriate links back and forth between them.

dhmlau · 2018-02-15T18:53:26Z

_data/sidebars/lb4_sidebar.yml

+    url: Hello-World.html
    output: 'web, pdf'

+  - title: 'Getting Started'


I'd actually prefer Getting Started being at the top level. That's usually the first place to look when people are starting out.

virkt25 · 2018-04-04T14:24:38Z

Closing as no longer needed.

kjdelisle requested a review from bschrammIBM as a code owner February 1, 2018 22:20

kjdelisle added the needs-priority label Feb 1, 2018

kjdelisle self-assigned this Feb 1, 2018

shimks reviewed Feb 5, 2018

View reviewed changes

bajtos suggested changes Feb 6, 2018

View reviewed changes

kjdelisle mentioned this pull request Feb 6, 2018

docs(example-getting-started): use openapi-v2 decorators in readme loopbackio/loopback-next#970

Merged

kjdelisle force-pushed the lb4/garden-path-tutorial branch from 35c20d5 to 8926125 Compare February 6, 2018 17:51

shimks approved these changes Feb 6, 2018

View reviewed changes

b-admike approved these changes Feb 6, 2018

View reviewed changes

dhmlau reviewed Feb 7, 2018

View reviewed changes

bajtos added this to the February 2018 milestone Feb 8, 2018

virkt25 reviewed Feb 8, 2018

View reviewed changes

kjdelisle force-pushed the lb4/garden-path-tutorial branch from eedb7c5 to bb86f04 Compare February 13, 2018 18:50

kjdelisle changed the title ~~docs(lb4): create garden path tutorial~~ docs(lb4): reorganize current tutorial materials Feb 13, 2018

dhmlau reviewed Feb 15, 2018

View reviewed changes

virkt25 mentioned this pull request Mar 27, 2018

Garden path tutorial - rename getting-started to todo, add tutorial to docs loopbackio/loopback-next#1199

Merged

7 tasks

virkt25 closed this Apr 4, 2018

virkt25 removed the needs-priority label Apr 4, 2018

dhmlau deleted the lb4/garden-path-tutorial branch October 10, 2018 17:14


		Before we can begin, you'll need to make sure you have some things installed:

		* [Node.js](https://nodejs.org/en/) at v6.x or greater

docs(lb4): reorganize current tutorial materials #601

docs(lb4): reorganize current tutorial materials #601

Uh oh!

Conversation

kjdelisle commented Feb 1, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kjdelisle commented Feb 1, 2018

Uh oh!

shimks left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shimks Feb 5, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kjdelisle Feb 6, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kjdelisle commented Feb 13, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

shimks commented Feb 13, 2018

Uh oh!

virkt25 commented Feb 13, 2018

Uh oh!

raymondfeng commented Feb 13, 2018

Uh oh!

dhmlau commented Feb 13, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bajtos commented Feb 14, 2018

Uh oh!

kjdelisle commented Feb 15, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

virkt25 commented Apr 4, 2018

Uh oh!

Reviewers

kjdelisle commented Feb 1, 2018 •

edited

Loading

shimks left a comment •

edited

Loading

shimks Feb 5, 2018 •

edited

Loading

kjdelisle Feb 6, 2018 •

edited

Loading

kjdelisle commented Feb 13, 2018 •

edited

Loading

dhmlau commented Feb 13, 2018 •

edited

Loading