docs: docs overhaul

README.md

@@ -1,17 +1,19 @@
+![Logo](https://github.com/ash-project/ash/blob/main/logos/cropped-for-header-black-text.png?raw=true#gh-light-mode-only)
+![Logo](https://github.com/ash-project/ash/blob/main/logos/cropped-for-header-white-text.png?raw=true#gh-dark-mode-only)
+
+![Elixir CI](https://github.com/ash-project/ash_state_machine/workflows/CI/badge.svg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Hex version badge](https://img.shields.io/hexpm/v/ash_state_machine.svg)](https://hex.pm/packages/ash_state_machine)
+[![Hexdocs badge](https://img.shields.io/badge/docs-hexdocs-purple)](https://hexdocs.pm/ash_state_machine)
+
 # AshStateMachine
 
-A state machine extension for `Ash.Resource`
+Welcome! This is the extension for building state machines with [Ash](https://hexdocs.pm/ash_state_machine) resources.
 
-## Installation
+## Tutorials
 
-```elixir
-def deps do
-  [
-    {:ash_state_machine, "~> 0.2.3-rc.0"}
-  ]
-end
-```
+- [Getting Started with AshStateMachine](documentation/tutorials/getting-started-with-ash-state-machine.md)
 
-## Get Started
+## Reference
 
-Check out the [getting started guide](/documentation/tutorials/get-started-with-state-machines.md).
+- [AshStateMachine DSL](documentation/dsls/DSL:-AshStateMachine.md)

documentation/tutorials/get-started-with-state-machines.md → documentation/tutorials/getting-started-with-ash-state-machine.md

@@ -7,12 +7,7 @@ If you haven't already, read the [Ash Getting Started Guide](https://hexdocs.pm/
 ## Bring in the ash_state_machine dependency
 
 ```elixir
-def deps()
-  [
-    ...
-    {:ash_state_machine, "~> 0.2.3-rc.0"}
-  ]
-end
+{:ash_state_machine, "~> 0.2.3-rc.0"}
 ```
 
 ## Making a resource into a state machine

mix.exs

@@ -4,7 +4,7 @@ defmodule AshStateMachine.MixProject do
   @version "0.2.3-rc.0"
 
   @description """
-  An Ash.Resource extension for building finite state machines
+  The extension for building state machines with Ash resources.
   """
 
   def project do
@@ -47,7 +47,7 @@ defmodule AshStateMachine.MixProject do
 
   defp docs do
     [
-      main: "get-started-with-state-machines",
+      main: "readme",
       source_ref: "v#{@version}",
       logo: "logos/small-logo.png",
       extra_section: "GUIDES",
@@ -77,7 +77,8 @@ defmodule AshStateMachine.MixProject do
           ""
       end,
       extras: [
-        "documentation/tutorials/get-started-with-state-machines.md",
+        {"README.md", title: "Home"},
+        "documentation/tutorials/getting-started-with-ash-state-machine.md",
         "documentation/dsls/DSL:-AshStateMachine.md"
       ],
       groups_for_extras: [