update intro sections in 2.x docs

docs/source/v2/difference-between-this-package-and-others.blade.md

@@ -7,18 +7,45 @@ section: content
 
 # Difference Between This Package And Others
 
-A frequently asked question is the difference between this package and [tenancy/multi-tenant](https://github.com/tenancy/multi-tenant).
+A frequently asked question is the difference between this package and other tenancy packages for Laravel.
 
-Packages like tenancy/multi-tenant and tenancy/tenancy give you an API for making your application multi-tenant. They give you a tenant DB connection, traits to apply on your models, a guide on creating your own tenant-aware cache, etc.
+## tenancy/multi-tenant (previously hyn/multi-tenant)
 
-This package (stancl/tenancy) makes your application multi-tenant automatically and attempts to make you not have to change anything in your code. The philosophy behind this approach is that you should write your app, not tenancy boilerplate.
+tenancy/multi-tenant gives you an API for making your application multi-tenant yourself. It gives you a tenant DB connection, traits to apply on your models, a guide on creating your own tenant-aware cache, etc.
 
-Apart from saving you a ton of time, the benefit of going with the automatic approach (stancl/tenancy) is that you can adapt easily, since you're not bound to a specific implementation of multi-tenancy. [You can always change how tenancy is bootstrapped.]({{ $page->link('tenancy-bootstrappers') }})
+## tenancy/tenancy (currently in alpha)
+
+tenancy/tenancy is even less opinionated and is more of a framework to write your own tenancy implementation. For example, there is no tenant object. There is a tenant interface that you implement on some model in your application.
+
+## stancl/tenancy
+
+This package takes a completely new approach to multi-tenancy.
+
+It makes your application multi-tenant automatically and attempts to make you not have to change anything in your code. The philosophy behind this approach is that you should write your app, not tenancy boilerplate.
+
+We belive that your code will be a lot cleaner if tenancy and the actual app don't mix. Why pollute your code with tons of tenancy implementations, when you can push all of tenancy one layer below your actual application?
+
+Apart from saving you a ton of time, the benefit of going with the automatic approach is that you can adapt easily, since you're not bound to a specific implementation of multi-tenancy. [You can always change how tenancy is bootstrapped.]({{ $page->link('tenancy-bootstrappers') }})
+
+This approach is also more secure. Say you have written a SaaS. The application is finished — now you just need to make it multi-tenant before releasing it. With the tenancy/\* packages, you will have to rewrite significant portions of your code and hope you did not forget to change each, for example, `Cache::` call to some tenant-aware cache that you implement yourself.
+
+With stancl/tenancy, you just install the package, decide what routes belong to the "central" part of the app and what routes belong to the tenant part of the app, and tell the config file on what domains you host the central app — the landing page & sign up form.
+
+Everything else happens automatically in the background:
+- Database connection is switched
+- Cache is made multi-tenant
+- Filesystem is made multi-tenant
+- Queued jobs are made multi-tenant
+- Redis is made multi-tenant
+
+This means that you can also integrate with any packages you would normally use, without any difficulties.
+
+We believe that this seamless approach to multi-tenancy is consistent with Laravel's "developer happiness from download to deploy".
 
 ## Which one should you use?
 
-Depends on what you prefer.
+If you want to implement multi-tenancy yourself by writing package-specific tenant-aware code, use tenancy/multi-tenant.
 
-If you want full control and make your application multi-tenant yourself, use tenancy/multi-tenant.
+If you want to be assisted in writing your own tenancy implementation, use tenancy/tenancy (currently in alpha).
 
-If you want to focus on writing your application instead of tenancy implementations, use stancl/tenancy.
+If you want to focus on writing your application instead of tenancy implementations, and have no problems trying to integrate other packages, use stancl/tenancy.

docs/source/v2/getting-started.blade.md

@@ -31,4 +31,4 @@ Multi-tenancy can be single-database and multi-database.
 **Single-database tenancy** means that your application uses only a single database. The way this is usually implemented is that instead of having the `id`, `title`, `user_id` and `body` columns in your `posts` table, you will also have a `tenant_id` column. This approach works until you need custom databases for your clients. It's also easy to implement, it basically boils down to having your models use a trait which adds a [global scope](https://laravel.com/docs/master/eloquent#global-scopes).
 Again, to be clear: This package does not provide single-database tenancy features.
 
-**Multi-database tenancy**, the type that this package provides, lets you use a separate database for each tenant. The benefits of this approach are scalability, compliance (some clients need to have the database on their server) and mitigation of risks such as showing the wrong tenant's data to a user. The downside is that this model is harder to implement, which is why this package exists.
+**Multi-database tenancy**, the type that this package provides, lets you use a separate database for each tenant. The benefits of this approach are scalability, compliance (some clients need to have the database on their server) and mitigation of risks such as showing the wrong tenant's data to a user.