various tweaks

Author: jasonvarga

content/collections/extending-docs/addons.md

@@ -18,12 +18,15 @@ php please make:addon example/my-addon
 
 This will scaffold out everything you need to get started as a [private addon](#private-addons) within your site's `addons` directory.
 
-Eventually, an addon will be available on Packagist and installable through Composer (and therefore live inside your `vendor` directory). During development however, you can keep it on your local filesystem as a path repository.
+Eventually, an addon may be available on Packagist and installable through Composer (and therefore live inside your `vendor` directory). During development however, you can keep it on your local filesystem as a path repository.
 
 :::tip
 If you don't plan on distributing your addon or sharing it between multiple projects, you can take a simpler approach and just [add things to your Laravel application](/extending).
 :::
 
+
+### What's in an addon?
+
 An addon consists of at least a `composer.json` and a service provider. Your directory may be placed anywhere, but for the sake of this example, we'll put it in `addons/acme/example`
 
 ``` files theme:serendipity-light
@@ -42,6 +45,13 @@ resources
 composer.json
 ```
 
+### Composer.json
+
+The composer.json is used by (you guessed it) Composer in order to install your package.
+
+The `extra.statamic` section is used by Statamic to know that it's an addon and not just a standard Composer package.
+The `extra.laravel.providers` section what Laravel uses to load your service provider.
+
 ``` json
 {
     "name": "acme/example",
@@ -73,6 +83,10 @@ composer.json
 }
 ```
 
+### Service Provider
+
+The service provider is where all the various components of your addon get wired together.
+
 You should make sure that your service provider extends Statamic's `Statamic\Providers\AddonServiceProvider`, and not `Illuminate\Support\ServiceProvider`. Statamic's `AddonServiceProvider` includes some bootstrapping and autoloading that isn't included with Laravel's service provider.
 
 ``` php
@@ -93,7 +107,11 @@ The `bootAddon` method should be used instead of `boot`. They are the same excep
 makes sure to boot _after_ Statamic has booted.
 :::
 
-In your project root's `composer.json`, add your package to the `require` and `repositories` sections, like so:
+### Installing your freshly created addon
+
+If you ran the `make:addon` command, this would have been taken care of for you. 
+
+Otherwise, in your project root's `composer.json`, add your package to the `require` and `repositories` sections, like so:
 
 ``` json
 {
@@ -128,7 +146,7 @@ Your addon is now installed. You should be able to go to `/cp/addons` and see it
 
 ### Public addons
 
-A public addon is one available as a composer package on packagist.org. Simple require it with composer:
+A public addon is one available as a composer package on packagist.org. Simply require it with composer:
 
 ``` shell
 composer require vendor/package
@@ -227,7 +245,7 @@ protected $commands = [
 ### CSS and Javascript
 The method of adding assets will differ slightly depending on whether you are using Vite or another build process. We recommend Vite.
 
-#### Using Vite
+#### Using Vite (recommended) {#using-vite}
 
 In your service provider, you may register your Vite config like this, adjusting the paths appropriately.
 
@@ -604,7 +622,7 @@ An example use case is a custom fieldtype maintained by a third party vendor. Ev
 
 ### Starters Kits
 
-- Starter kits are installed via `php please starter-kit:install`
+- Starter kits are installed via `statamic new` or `php please starter-kit:install`
 - Starter kits install pre-configured files and settings into your site
 - Starter kits do not live as updatable packages within your apps
 - Starter kit licenses are not tied to a specific site, and expire after a successful install

content/collections/extending-docs/tags.md

@@ -166,10 +166,10 @@ public function missing($tag)
 }
 ```
 
-
-
-You may have used the `__call()` magic method in Statamic v2 to handle wildcard tags. This still technically works, but we've
-introduced the `wildcard` method to prevent some infinite looping situations you may encounter.
+:::best-practice
+You may notice that the `wildcard` method seems very similar to the `__call()` magic method. It is! The `wildcard` method
+uses `__call` under the hood, but with additional smarts. Be sure to use `wildcard`!
+:::
 
 ## Generating a tag class
 

content/collections/extending-docs/widgets.md

@@ -6,7 +6,13 @@ updated_at: 1569264107
 id: 5900c99f-89b9-4ee3-834c-cb1b070146e4
 ---
 
-For widgets, start with `php please make:widget LocalWeather`.
+## Generating a widget
+
+You can generate a widget with a console command:
+
+```shell
+php please make:widget LocalWeather
+```
 
 This will automagically set up the widget and create a base template file at `resources/views/widgets/local_weather.blade.php`.
 

content/collections/sections/extending.md

@@ -8,15 +8,16 @@ section: extending_docs
 ---
 ## To addon, or not to addon?
 
-In Statamic v2, practically every customization would need to be contained within an addon, even if you had no intention of distributing it.
+Since Statamic is a Laravel package, you are in control over your application code.
 
-Since Statamic v3 is a Laravel package, you are in control over your application code. You're free to add whatever extra code you like.
-
-This makes the distinction much clearer: **If you want to reuse, distribute, or sell your features; you should make an addon.** Otherwise, you can just add things to your Laravel application.
+**If you want to reuse, distribute, or sell your features; you should make an addon.** Otherwise, you can just add things to your Laravel application.
 
 ## How to extend Statamic
 
-Some features can simply be placed in the right spot and they'll be wired up automatically. For example, placing a [tag](/extending/tags) class inside `app/Tags` will make it available to your templates without any extra wiring.
+Many features can simply be placed in the right spot and they'll be wired up automatically.
+
+For example, placing a [Tag](/extending/tags) class inside `app/Tags` will make it available to your templates without any extra wiring.
+Or if you're building an addon, putting it in `src/Tags` will do the same.
 
 Others could require some wiring, which would typically go in a service provider.