docs: move around some docs, and update the development-utilities guide

documentation/home.md

@@ -33,6 +33,11 @@ Welcome to the Ash Framework documentation! Here you will find everything you ne
 
 - [Glossary](documentation/topics/glossary.md)
 
+### Development
+
+- [Development Utilities](documentation/topics/development/development-utilities.md)
+- [Upgrading to 3.0](documentation/topics/development/upgrading-to-3.0.md)
+
 ### About Ash
 
 - [What is Ash?](documentation/topics/about_ash/what-is-ash.md)

documentation/topics/development/development-utilities.md

@@ -2,15 +2,11 @@
 
 ## ElixirSense Plugin
 
-The Ash ElixirSense plugin offers custom auto complete inside of any Ash DSL module (i.e `Ash.Resource`/`Ash.Domain`)
-
-As of this writing, this does not work with the currently released VSCode package. We are waiting for them to do another release
-to resolve this issue. However, you can clone down the elixir-ls repository, run its release command, and configure VSCode to point
-at the folder where you did that.
+Ash uses [Spark](https://hexdocs.pm/spark) to build all of our DSLs (like `Ash.Resource` and `Ash.Domain`) and to validate options lists to functions. `Spark` ships with an extension that is automatically picked up by ElixirLS to provide autocomplete for all of our DSLs, and options list. You don't need to do anything to enable this, but it only works with ElixirLS (not other language server tools).
 
 ## Formatter plugin
 
-The underlying DSL tooling `Spark` has a formatter plugin that can help you keep your resources consistent and neat.
+`Spark` also ships with a formatter plugin that can help you keep your resources formatted consistently. This plugin can sort the sections of your DSL to make your resources more consistent, and it can ensure that the DSL builders don't have parenthesis around them. (i.e `attribute :foo, :bar` vs `attribute(:foo, :bar)`).
 
 ### Adding the plugin
 
@@ -30,20 +26,20 @@ Add the following to your `.formatter.exs`
 ```elixir
 config :spark, :formatter,
   remove_parens?: true,
+  "Ash.Domain": [],
   "Ash.Resource": [
-    type: Ash.Resource,
     section_order: [
-      :authentication,
-      :token,
+      # any section not in this list is left where it is
+      # but these sections will always appear in this order in a resource
+      :actions,
       :attributes,
       :relationships,
-      :policies,
-      :postgres
+      :identities
     ]
   ]
 ```
 
-#### If you use a different module than Ash.Resource
+#### If you `use` a different module than Ash.Resource
 
 ```elixir
 config :spark, :formatter,

documentation/topics/extending-resources.md

@@ -195,11 +195,11 @@ defmodule MyApp.Tweet do
 end
 ```
 
-Your extension will be automatically supported by the `elixir_sense` extension, showing inline documentation and auto complete as you type. For more on that, see p[Development Utilities](/documentation/topics/development-utilities.md)
+Your extension will be automatically supported by the `elixir_sense` extension, showing inline documentation and auto complete as you type. For more on that, see p[Development Utilities](/documentation/topics/development/development-utilities.md)
 
 ## Making a Base Resource
 
-The "Base Resource" pattern has been adopted by some as a way to make it easy to ensure that your base extension is used everywhere. Instead of using `Ash.Resource` you use `MyApp.Resource`. Take a look at the [Development Utilities](/documentation/topics/development-utilities.md) guide if you do this, as you will need to update your formatter configuration, if you are using it.
+The "Base Resource" pattern has been adopted by some as a way to make it easy to ensure that your base extension is used everywhere. Instead of using `Ash.Resource` you use `MyApp.Resource`. Take a look at the [Development Utilities](/documentation/topics/development/development-utilities.md) guide if you do this, as you will need to update your formatter configuration, if you are using it.
 
 ```elixir
 defmodule MyApp.Resource do
@@ -218,4 +218,4 @@ And now you can use it with your resources like this:
 defmodule MyApp.Tweet do
   use MyApp.Resource
 end
-```
+```

mix.exs

@@ -46,12 +46,13 @@ defmodule Ash.MixProject do
         "documentation/topics/about_ash/what-is-ash.md",
         "documentation/topics/about_ash/design-principles.md",
         "documentation/topics/about_ash/contributing-to-ash.md",
+        "documentation/topics/development/development-utilities.md",
+        "documentation/topics/development/upgrading-to-3.0.md",
         "CHANGELOG.md",
         "documentation/how_to/define-idiomatic-actions.md",
         "documentation/how_to/defining-manual-relationships.md",
         "documentation/how_to/handle-errors.md",
         "documentation/how_to/structure-your-project.md",
-        "documentation/how_to/upgrade.md",
         "documentation/how_to/use-without-data-layers.md",
         "documentation/how_to/validate-changes.md",
         "documentation/how_to/auto-format-code.md",
@@ -63,7 +64,6 @@ defmodule Ash.MixProject do
         "documentation/topics/calculations.md",
         "documentation/topics/code-interface.md",
         "documentation/topics/constraints.md",
-        "documentation/topics/development-utilities.md",
         "documentation/topics/embedded-resources.md",
         "documentation/topics/extending-resources.md",
         "documentation/topics/expressions.md",
@@ -101,11 +101,14 @@ defmodule Ash.MixProject do
         Topics: [
           "documentation/topics/glossary.md"
         ],
+        "Development": [
+          "documentation/topics/development/development-utilities.md",
+          "documentation/topics/development/upgrading-to-3.0.md"
+        ],
         "About Ash": [
           "documentation/topics/about_ash/what-is-ash.md",
           "documentation/topics/about_ash/design-principles.md",
           "documentation/topics/about_ash/contributing-to-ash.md",
-          "documentation/topics/upgrading-to-3.0.md",
           "CHANGELOG.md"
         ],
         "How To": [],
@@ -137,7 +140,6 @@ defmodule Ash.MixProject do
           "documentation/topics/calculations.md",
           "documentation/topics/code-interface.md",
           "documentation/topics/constraints.md",
-          "documentation/topics/development-utilities.md",
           "documentation/topics/embedded-resources.md",
           "documentation/topics/extending-resources.md",
           "documentation/topics/expressions.md",
@@ -161,7 +163,7 @@ defmodule Ash.MixProject do
       skip_undefined_reference_warnings_on: [
         "CHANGELOG.md",
         "documentation/topics/glossary.md",
-        "documentation/topics/upgrading-to-3.0.md"
+        "documentation/topics/development/upgrading-to-3.0.md"
       ],
       nest_modules_by_prefix: [
         Ash.Error,