docs(example-getting-started): split tutorial into separate files #1001

kjdelisle · 2018-02-15T17:44:35Z

Break up the pieces of the tutorial so that they can be served as individual links on LoopBack.io
under the LB4 docs.

re #729

Checklist

npm test passes on your machine
New tests added or existing tests modified to cover all changes
Code conforms with the style guide
Related API Documentation was updated
Affected artifact templates in packages/cli were updated
Affected example projects in packages/example-* were updated

raymondfeng

Great work to make the guide progressive!

Please address my comment before merging.

raymondfeng · 2018-02-15T19:13:32Z

packages/example-getting-started/docs/8-putting-it-together.md

+
+Now that your app is ready to go, try it out with your favourite REST client!
+Start the app (`npm start`) and then make some REST requests:
+- `POST /todo` with a body of `{ "title": "get the milk" }`


We probably should illustrate the usage of API Explorer and/or curl here.

I don't intend to improve the individual documents at this time. There's quite a bit of work required across all of the pieces to make it a more cohesive and instructive tutorial, but I want to make sure that the wireup between this repository and loopback.io is finished first.

That's fair. I'm fine with follow-up PRs.

b-admike · 2018-02-15T21:25:29Z

packages/example-getting-started/docs/1-prerequisites-and-setup.md

@@ -0,0 +1,30 @@
+## Prerequisites


Can we signify that if they are to follow the instructions here, they get the fully functional app, and if they follow the other steps, they're following a tutorial to build it?

See #1001 (comment)

virkt25

Haven't reviewed the content of the files. Not sure if I'm reviewing content or there will be follow up PRs for that as per your comment to Raymond.

virkt25 · 2018-02-15T21:16:27Z

packages/cli/test/clone-example.test.js

          glob('**', {
            cwd: path.join(__dirname, `../../example-${VALID_EXAMPLE}`),
-            ignore: '@(node_modules|dist*|api-docs)/**',
+            ignore: '@(node_modules|dist*|api-docs|docs)/**',


I think this is no longer needed ... right?

Break up the pieces of the tutorial so that they can be served as individual links on LoopBack.io under the LB4 docs. re #729

shimks

I started review on the documents, but then I read your comments on intending to improve the contents of the documents later on, so just ignore my comments (or have it in the back of your mind for when you do change up the contents inside).

shimks · 2018-02-15T21:19:56Z

packages/example-getting-started/docs/1-prerequisites-and-setup.md

+## Prerequisites
+
+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


shimks · 2018-02-15T21:21:36Z

packages/example-getting-started/docs/2-scaffold-app.md

@@ -0,0 +1,13 @@
+### Create your app scaffolding
+
+Install the `@loopback/cli` package. This will give you the command-line


This has been covered in the prerequisite page. This line should be phrased so that it 'remind' the users to have it installed instead

shimks · 2018-02-15T21:23:19Z

packages/example-getting-started/docs/2-scaffold-app.md

+toolkit that can generate a basic REST app for you.
+`npm i -g @loopback/cli`
+
+Next, navigate to whichever directory you'd like to create your new project


I'm already confused here. The previous page tells me to download example-getting-started but we don't do anything with it? Maybe we should clarify somewhere that example-getting-started has only been downloaded for users' reference

shimks · 2018-02-15T21:24:20Z

packages/example-getting-started/docs/3-add-legacy-juggler.md

+import {ApplicationConfig} from '@loopback/core';
+import {RestApplication} from '@loopback/rest';
+import {PingController} from './controllers/ping-controller';
+import {Class, Repository, RepositoryMixin} from '@loopback/repository';


We don't use Class or Repository yet

shimks · 2018-02-15T21:25:14Z

packages/example-getting-started/docs/4-todo-model.md

@@ -0,0 +1,104 @@
+### Building the Todo model
+
+The Todo model will be the object we use both as a Data Transfer Object (DTO) on


A link to what a Data Transfer Object might be helpful, unless we assume users know what this is (I don't 😆 ).

shimks · 2018-02-15T21:31:41Z

packages/example-getting-started/docs/4-todo-model.md

+// elsewhere...
+
+// with index.ts
+import {Foo, Bar, Baz} from './models';


Isn't there the danger of creating circular dependencies here? The examples use models, but what if they were something with complicated dependencies? I remember having to go and change the imports around so that they were imported straight from their original files instead of from index.ts to solve some problems I was having.

shimks · 2018-02-15T21:32:27Z

packages/example-getting-started/docs/4-todo-model.md

+- a unique id
+- a title
+- a description that details what the todo is all about
+- a boolean flag for whether or not we've completed the task.


consistent periods or not at all please

shimks · 2018-02-15T21:33:55Z

packages/example-getting-started/docs/4-todo-model.md

+- a description that details what the todo is all about
+- a boolean flag for whether or not we've completed the task.
+
+For the Legacy Juggler to understand how to work with our model class, it


Not a grammar master, but we might need a comma here: Legacy Juggler, to. Or we might need to change the phrasing so that we don't have too many commas in this sentence.

kjdelisle · 2018-02-15T21:47:40Z

Travis is still all gummed up on macOS right now, so going to go ahead and land this.

bajtos · 2018-02-16T09:10:01Z

@kjdelisle the new README looks pretty useless to me:

Please make sure to beef it up in your follow-up pull requests, so that people consuming this content from GitHub and/or lb4 example getting-started have a good experience too!

At minimum, I would expect a TOC-like list pointing to individual files ("chapters").

kjdelisle self-assigned this Feb 15, 2018

kjdelisle requested review from bajtos and raymondfeng as code owners February 15, 2018 17:44

kjdelisle added the needs-priority label Feb 15, 2018

kjdelisle mentioned this pull request Feb 15, 2018

docs(lb4): reorganize current tutorial materials loopbackio/loopback.io#601

Closed

kjdelisle force-pushed the example-getting-started/tutorial-refactor branch from 2e5ab1b to 4640e6c Compare February 15, 2018 17:54

kjdelisle mentioned this pull request Feb 15, 2018

test(cli): disable GitHub cloning tests #1003

Merged

6 tasks

raymondfeng requested changes Feb 15, 2018

View reviewed changes

kjdelisle force-pushed the example-getting-started/tutorial-refactor branch from 4640e6c to 1ab8100 Compare February 15, 2018 21:03

b-admike reviewed Feb 15, 2018

View reviewed changes

virkt25 reviewed Feb 15, 2018

View reviewed changes

raymondfeng approved these changes Feb 15, 2018

View reviewed changes

docs(example-getting-started): split tutorial into separate files

70fba54

Break up the pieces of the tutorial so that they can be served as individual links on LoopBack.io under the LB4 docs. re #729

kjdelisle force-pushed the example-getting-started/tutorial-refactor branch from 1ab8100 to 70fba54 Compare February 15, 2018 21:32

shimks approved these changes Feb 15, 2018

View reviewed changes

kjdelisle merged commit e5410b6 into master Feb 15, 2018

kjdelisle removed the needs-priority label Feb 15, 2018

kjdelisle deleted the example-getting-started/tutorial-refactor branch February 15, 2018 21:47

kjdelisle mentioned this pull request Feb 16, 2018

docs(example-getting-started): add links to tutorial paths #1012

Merged

6 tasks

		@@ -0,0 +1,13 @@
		### Create your app scaffolding

		Install the `@loopback/cli` package. This will give you the command-line

		@@ -0,0 +1,104 @@
		### Building the Todo model

		The Todo model will be the object we use both as a Data Transfer Object (DTO) on

docs(example-getting-started): split tutorial into separate files #1001

docs(example-getting-started): split tutorial into separate files #1001

Uh oh!

Conversation

kjdelisle commented Feb 15, 2018

Checklist

Uh oh!

raymondfeng left a comment

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!

virkt25 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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!

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 15, 2018

Uh oh!

bajtos commented Feb 16, 2018

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

shimks left a comment •

edited

Loading