Improvements to the Getting Started guide #406

moonglum · 2017-10-27T06:53:43Z

I've just made my way through the Getting Started guide. It's really well written, thank you for that 😄 I noticed some things along the way that could be improved in my opinion – I've added some comments to the changes I made in the 1.1 guide (the changes in the 1.0 are the same ones).

moonglum · 2017-10-27T06:54:15Z

source/guides/1.1/getting-started.md

@@ -319,7 +319,7 @@ To make our test pass, we need to edit our newly generated template file in `app
 </div>
 ```

-Save your changes and see your tests pass!
+Save your changes and see your tests pass! The output will also contain a skipped test. This is due to an autogenerated test in `spec/web/views/books/index_spec.rb`.


I think this should be said explicitly, because it might confuse people.

moonglum · 2017-10-27T06:54:50Z

source/guides/1.1/getting-started.md

@@ -386,7 +386,7 @@ The generator gives us an entity, a repository, a migration, and accompanying te

 ### Migrations To Change Our Database Schema

-Let's modify the generated migration to include `title` and `author` fields:
+Let's modify the generated migration (the path to the migration will differ for you, because it contains a timestamp) to include `title` and `author` fields:


I copied the path to migration and messed up my development database, because it tried to create the books twice 😉

moonglum · 2017-10-27T06:55:04Z

source/guides/1.1/getting-started.md

@@ -422,7 +422,7 @@ Let's prepare our database for the development and test environments:
 An entity is something really close to a plain Ruby object.
 We should focus on the behaviors that we want from it and only then, how to save it.

-For now, we need to create simple entity class:
+For now, we keep the generated entity class:


Nothing changed about this file, so we should state that.

moonglum · 2017-10-27T06:55:39Z

source/guides/1.1/getting-started.md

@@ -435,7 +435,7 @@ We can verify it all works as expected with a unit test:

 ```ruby
 # spec/bookshelf/entities/book_spec.rb
-require 'spec_helper'
+require_relative '../../spec_helper'


I noticed that the generators generate the tests with a require_relative. I think either the generator or the guide should be adjusted.

moonglum · 2017-10-27T06:56:08Z

source/guides/1.1/getting-started.md

@@ -506,8 +506,7 @@ Let's write a test to force this change in our view:

 ```ruby
 # spec/web/views/books/index_spec.rb
-require 'spec_helper'
-require_relative '../../../../apps/web/views/books/index'


The generator also doesn't require the files. Again: I think either the generator or the guide should be adjusted.

moonglum · 2017-10-27T06:56:32Z

source/guides/1.1/getting-started.md


-6 runs, 7 assertions, 0 failures, 0 errors, 0 skips
+9 runs, 16 assertions, 0 failures, 0 errors, 0 skips


We autogenerated some tests, so these coutns were wrong.

moonglum · 2017-10-27T06:57:20Z

source/guides/1.1/getting-started.md

@@ -768,7 +765,7 @@ describe Web::Controllers::Books::Create do
 end
 ```

-Making these tests pass is easy enough.
+Let's make these tests pass!


In my experience it is not a good idea to tell someone that something is "easy enough". What if the reader did not understand it? They might feel pretty stupid when they are told that this is supposed to be easy.

moonglum · 2017-10-27T06:57:35Z

source/guides/1.1/getting-started.md


 # Running:

-...............
+...S.S.........


Again, some auto generated tests are skipped.

But the seed? Changing it doesn't make much sense to me.

moonglum · 2017-10-27T06:58:05Z

source/guides/1.1/getting-started.md

@@ -980,7 +976,7 @@ end
 ```

 In our template we can loop over `params.errors` (if there are any) and display a friendly message.
-Open up `apps/web/templates/books/new.html.erb`:
+Open up `apps/web/templates/books/new.html.erb` and add the following at the top of the file:


Up until now we always presented the entire file. Here we only show a piece of it. Maybe we should just paste the entire file here as well?

moonglum · 2017-10-27T06:58:56Z

source/guides/1.1/getting-started.md

@@ -1031,7 +1029,7 @@ resources :books, only: [:index, :new, :create]
 ```

 To get a sense of what routes are defined, now we've made this change, you can
-use the special command-line task `routes` to inspect the end result:
+run `bundle exec hanami routes` on your command-line to inspect the end result:


I think it makes sense to tell the reader what they should run in their command-line.

moonglum · 2017-10-27T06:59:39Z

source/guides/1.1/getting-started.md

@@ -1056,7 +1054,7 @@ Remember how we built our form using `form_for`?
 %>
 ```

-It's silly to include a hard-coded path in our template, when our router is already perfectly aware of which route to point the form to.
+We don't need to include a hard-coded path in our template, when our router is already perfectly aware of which route to point the form to.


I think calling something the reader did "silly" is not a good idea.

moonglum · 2017-11-02T17:01:56Z

Hey 👋 Just wanted to know what the status is here 😺

marionschleifer · 2017-11-03T10:17:47Z

Hi @moonglum, thanks very much for your contribution. I've been on holidays for a week, but I will look at it until Sunday :-)

moonglum · 2017-11-03T13:28:37Z

@marionschleifer That's amazing! Thank you 🙇

apohllo · 2017-11-03T13:50:34Z

source/guides/1.0/getting-started.md

@@ -177,7 +177,7 @@ As you can see, we have set `HANAMI_ENV` environment variable to instruct our co
 Now we have a test, we can see it fail:

 ```
-% rake test
+% bundle exec rake test


apohllo · 2017-11-03T13:50:56Z

source/guides/1.0/getting-started.md

@@ -319,7 +319,7 @@ To make our test pass, we need to edit our newly generated template file in `app
 </div>
 ```

-Save your changes and see your tests pass!
+Save your changes and see your tests pass! The output will also contain a skipped test. This is due to an autogenerated test in `spec/web/views/books/index_spec.rb`.


apohllo · 2017-11-03T13:51:45Z

source/guides/1.0/getting-started.md

@@ -347,7 +347,7 @@ Open up the file `apps/web/templates/application.html.erb` and edit it to look l
 </html>
 ```

-Now you can remove the duplicate lines from the other templates.
+Now you can remove the duplicate lines from the other templates. Let's run the tests again to check that everything worked fine.


Maybe a command running the tests should be inserted here?

apohllo · 2017-11-03T13:52:02Z

source/guides/1.0/getting-started.md

@@ -386,7 +386,7 @@ The generator gives us an entity, a repository, a migration, and accompanying te

 ### Migrations To Change Our Database Schema

-Let's modify the generated migration to include `title` and `author` fields:
+Let's modify the generated migration (the path to the migration will differ for you, because it contains a timestamp) to include `title` and `author` fields:


apohllo · 2017-11-03T13:53:36Z

source/guides/1.0/getting-started.md

@@ -422,7 +422,7 @@ Let's prepare our database for the development and test environments:
 An entity is something really close to a plain Ruby object.
 We should focus on the behaviors that we want from it and only then, how to save it.

-For now, we need to create simple entity class:
+For now, we keep the generated entity class:


👍 The class is already created by the generator.

apohllo · 2017-11-03T13:58:11Z

source/guides/1.0/getting-started.md

@@ -1031,7 +1029,7 @@ resources :books, only: [:index, :new, :create]
 ```

 To get a sense of what routes are defined, now we've made this change, you can
-use the special command-line task `routes` to inspect the end result:
+run `bundle exec hanami routes` on your command-line to inspect the end result:


Hmm, the actual command is below. IMHO it's better to keep the original wording, since it makes the user acquainted with what a "task" means.

apohllo · 2017-11-03T13:59:06Z

source/guides/1.0/getting-started.md

@@ -1056,7 +1054,7 @@ Remember how we built our form using `form_for`?
 %>
 ```

-It's silly to include a hard-coded path in our template, when our router is already perfectly aware of which route to point the form to.
+We don't need to include a hard-coded path in our template, when our router is already perfectly aware of which route to point the form to.


apohllo · 2017-11-03T13:59:22Z

source/guides/1.1/getting-started.md

@@ -319,7 +319,7 @@ To make our test pass, we need to edit our newly generated template file in `app
 </div>
 ```

-Save your changes and see your tests pass!
+Save your changes and see your tests pass! The output will also contain a skipped test. This is due to an autogenerated test in `spec/web/views/books/index_spec.rb`.


apohllo · 2017-11-03T14:00:47Z

source/guides/1.1/getting-started.md


 # Running:

-...............
+...S.S.........


But the seed? Changing it doesn't make much sense to me.

apohllo · 2017-11-03T14:01:04Z

source/guides/1.1/getting-started.md

@@ -980,7 +976,7 @@ end
 ```

 In our template we can loop over `params.errors` (if there are any) and display a friendly message.
-Open up `apps/web/templates/books/new.html.erb`:
+Open up `apps/web/templates/books/new.html.erb` and add the following at the top of the file:


moonglum · 2017-11-03T15:08:28Z

Adressed @apohllo's comments in f78bc22

marionschleifer

Great work, thanks a lot @moonglum 👍

marionschleifer · 2017-11-06T19:21:29Z

Dear @moonglum thank you very much for your great contribution 🌷 If you would like me to send you some Hanami stickers, please send me your postal address via email (marion.schleifer@gmail.com) 😃

moonglum · 2017-11-07T08:24:56Z

@marionschleifer Thank you so much 👍 More contributions will be coming soon 😸

moonglum commented Oct 27, 2017

View reviewed changes

jodosha assigned marionschleifer Oct 27, 2017

apohllo reviewed Nov 3, 2017

View reviewed changes

Improvements to the Getting Started guide

f78bc22

marionschleifer approved these changes Nov 6, 2017

View reviewed changes

marionschleifer merged commit 7030571 into hanami:build Nov 6, 2017

moonglum deleted the getting-started-improvements branch November 7, 2017 08:24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improvements to the Getting Started guide #406

Improvements to the Getting Started guide #406

moonglum commented Oct 27, 2017 •

edited

Loading

moonglum Oct 27, 2017

apohllo Nov 3, 2017

moonglum Oct 27, 2017

moonglum Oct 27, 2017

moonglum Oct 27, 2017

moonglum Oct 27, 2017

moonglum Oct 27, 2017

moonglum Oct 27, 2017

moonglum Oct 27, 2017

apohllo Nov 3, 2017

moonglum Oct 27, 2017

apohllo Nov 3, 2017

moonglum Oct 27, 2017

moonglum Oct 27, 2017

moonglum commented Nov 2, 2017

marionschleifer commented Nov 3, 2017

moonglum commented Nov 3, 2017

apohllo Nov 3, 2017

apohllo Nov 3, 2017

apohllo Nov 3, 2017

apohllo Nov 3, 2017

apohllo Nov 3, 2017

apohllo Nov 3, 2017

apohllo Nov 3, 2017

apohllo Nov 3, 2017

apohllo Nov 3, 2017

apohllo Nov 3, 2017

moonglum commented Nov 3, 2017

marionschleifer left a comment •

edited

Loading

marionschleifer commented Nov 6, 2017

moonglum commented Nov 7, 2017


		6 runs, 7 assertions, 0 failures, 0 errors, 0 skips
		9 runs, 16 assertions, 0 failures, 0 errors, 0 skips

Improvements to the Getting Started guide #406

Improvements to the Getting Started guide #406

Conversation

moonglum commented Oct 27, 2017 • edited Loading

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

moonglum commented Nov 2, 2017

marionschleifer commented Nov 3, 2017

moonglum commented Nov 3, 2017

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

moonglum commented Nov 3, 2017

marionschleifer left a comment • edited Loading

Choose a reason for hiding this comment

marionschleifer commented Nov 6, 2017

moonglum commented Nov 7, 2017

moonglum commented Oct 27, 2017 •

edited

Loading

marionschleifer left a comment •

edited

Loading