docs: tutorial improvements (#10674)

docs/getting-started.md

@@ -90,7 +90,7 @@ Sequelize will keep the connection open by default, and use the same connection
 
 ## Modeling a table
 
-Models are defined with `Sequelize.Model.init(attributes, options)`:
+A model is a class that extends `Sequelize.Model`. Models can be defined in two equivalent ways. The first, with `Sequelize.Model.init(attributes, options)`:
 
 ```js
 const Model = Sequelize.Model;
@@ -111,7 +111,7 @@ User.init({
 });
 ```
 
-Alternatively (legacy):
+Alternatively, using `sequelize.define`:
 
 ```js
 const User = sequelize.define('User', {
@@ -129,7 +129,9 @@ const User = sequelize.define('User', {
 });
 ```
 
-The above code tells Sequelize to expect a table named `users` in the database with the fields `firstName` and `lastName`. The table name is automatically pluralized by default (a library called [inflection](https://www.npmjs.com/package/inflection) is used under the hood to do this). This behavior can be stopped for a specific model by using the `freezeTableName: true` option, or for all models by using the `define` option from the Sequelize constructor.
+Internally, `sequelize.define` calls `Model.init`.
+
+The above code tells Sequelize to expect a table named `users` in the database with the fields `firstName` and `lastName`. The table name is automatically pluralized by default (a library called [inflection](https://www.npmjs.com/package/inflection) is used under the hood to do this). This behavior can be stopped for a specific model by using the `freezeTableName: true` option, or for all models by using the `define` option from the [Sequelize constructor](http://docs.sequelizejs.com/class/lib/sequelize.js~Sequelize.html#instance-constructor-constructor).
 
 Sequelize also defines by default the fields `id` (primary key), `createdAt` and `updatedAt` to every model. This behavior can also be changed, of course (check the API Reference to learn more about the available options).
 
@@ -155,7 +157,7 @@ class Bar extends Model {}
 Bar.init({ /* ... */ }, { sequelize, timestamps: true });
 ```
 
-You can read more about creating models in the [define API Reference](/class/lib/sequelize.js~Sequelize.html#instance-method-define) and the [Model API reference](/class/lib/model.js~Model.html).
+You can read more about creating models in the [Model.init API Reference](/class/lib/model.js~Model.html#static-method-init), or in the [sequelize.define API reference](/class/lib/sequelize.js~Sequelize.html#instance-method-define).
 
 ## Synchronizing the model with the database
 

docs/index.md

@@ -23,7 +23,7 @@ Sequelize is a promise-based Node.js ORM for Postgres, MySQL, MariaDB, SQLite an
 
 Sequelize follows [SEMVER](http://semver.org). Supports Node v6 and above to use ES6 features.
 
-**Sequelize v5** was released on March 13, 2019.
+**Sequelize v5** was released on March 13, 2019. [Official TypeScript typings are now included](manual/typescript).
 
 You are currently looking at the **Tutorials and Guides** for Sequelize. You might also be interested in the [API Reference](identifiers).
 
@@ -33,7 +33,7 @@ You are currently looking at the **Tutorials and Guides** for Sequelize. You mig
 const Sequelize = require('sequelize');
 const sequelize = new Sequelize('postgres://user:pass@example.com:5432/dbname');
 
-class User extends Model {}
+class User extends Sequelize.Model {}
 User.init({
   username: Sequelize.STRING,
   birthday: Sequelize.DATE
@@ -49,4 +49,4 @@ sequelize.sync()
   });
 ```
 
-To learn more about how to use Sequelize, read the tutorials available in the left menu. [Begin with Getting Started](manual/getting-started).
+To learn more about how to use Sequelize, read the tutorials available in the left menu. Begin with [Getting Started](manual/getting-started).

docs/models-definition.md

@@ -200,7 +200,7 @@ Foo.init({
   sequelize,
 });
 
-// legacy with `sequelize.define`
+// Or with `sequelize.define`
 sequelize.define('Foo', {
   firstname: Sequelize.STRING,
   lastname: Sequelize.STRING
@@ -219,7 +219,7 @@ sequelize.define('Foo', {
       this.setDataValue('lastname', names.slice(-1).join(' '));
     }
   }
-} );
+});
 ```
 
 ### Helper functions for use inside getter and setter definitions

docs/typescript.md

 # TypeScript
 
-Since v5 Sequelize provides it's own TypeScript definitions.
-Please note that only TS >= 3.1 is supported.
+Since v5, Sequelize provides its own TypeScript definitions. Please note that only TS >= 3.1 is supported.
 
-## Installation
-
-In order to avoid installation bloat for non TS users you must install the following packages manually:
+As Sequelize heavily relies on runtime property assignments, TypeScript won't be very useful out of the box. A decent amount of manual type declarations are needed to make models workable.
 
-- `@types/node` this is universally required
-- `@types/validator`
-- `@types/bluebird`
-
-## Note
+## Installation
 
-As Sequelize heavily relies on runtime property assignments, TypeScript won't be very useful out of the box.
-A decent amount of manual type declarations are needed to make models workable.
+In order to avoid installation bloat for non TS users, you must install the following typing packages manually:
+ - `@types/node` (this is universally required)
+ - `@types/validator`
+ - `@types/bluebird`
 
 ## Usage
 
@@ -129,11 +124,9 @@ async function stuff() {
 }
 ```
 
-## Legacy `.define` usage
+## Usage of `sequelize.define`
 
-TypeScript doesn't know how to generate a `class` definition when we use the legacy `.define`,
-therefor we need to do some manual work and declare an interface and a type and eventually cast
-the result of `.define` to the _static_ type.
+TypeScript doesn't know how to generate a `class` definition when we use the `sequelize.define` method to define a Model. Therefore, we need to do some manual work and declare an interface and a type, and eventually cast the result of `.define` to the _static_ type.
 
 ```ts
 // We need to declare an interface for our model that is basically what our class would be
@@ -147,7 +140,7 @@ type MyModelStatic = typeof Model & {
   new (values?: object, options?: BuildOptions): MyModel;
 }
 
-// TS can't derive a proper class definition from a `.define` call, therefor we need to cast here.
+// TS can't derive a proper class definition from a `.define` call, therefore we need to cast here.
 const MyDefineModel = <MyModelStatic>sequelize.define('MyDefineModel', {
   id: {
     primaryKey: true,