docs: updates documentation with rationale behind Nixago

.github/settings.yml

@@ -14,7 +14,7 @@
 
 repository:
   name: nixago
-  description: description of repoGenerate configuration files with Nix + CUE
+  description: The central source of truth for your development tools
   homepage: https://jmgilman.github.io/nixago/
   topics: nix, cuelang, development, developer-tools, development-environment
   default_branch: master

README.md

@@ -13,66 +13,26 @@
     </a>
 </p>
 
-> Generate configuration files with [Nix][1] + [CUE][2]
+> The central source of truth for your development tools
+
+Are you tired of having multiple configuration files for your development tools
+littering the root of your repositories? Nixago aims to allow your local
+`flake.nix` to act as the central source of truth for configuring your
+development tools. You can declare the configuration for all of your development
+tools in your flake file and Nixago will do the work of generating and
+maintaining the configuration files for you.
 
 ## Features
 
-- Specify configuration data using native Nix syntax
+- Specify configuration data using native [Nix][1] syntax
 - Validate configuration data using the language features from [Cue][2]
 - Generate configuration files in any of the [supported formats][3]
 - Places all artifacts in the Nix store
-- Provides plugins for generating several types of development configuration
-  files
+- Provides [plugins][4] for generating several types of configuration files
 
 ## Usage
 
-Add the flake as an input:
-
-```nix
-{ #....
-  inputs = {
-    # ...
-    nixago.url = "github:jmgilman/nixago";
-  };
-}
-```
-
-Plugins are available for quickly generating configuration files. For example, a
-[pre-commit][4] configuration:
-
-```nix
-{
-# ...
-    preCommitConfig = {
-        nixpkgs-fmt = {
-            entry = "${pkgs.nixpkgs-fmt}/bin/nixpkgs-fmt";
-            language = "system";
-            files = "\\.nix";
-        };
-    };
-
-    preCommit = nixago.plugins.pre-commit.mkLocalConfig {
-        configData = preCommitConfig;
-    };
-# ...
-}
-```
-
-The flake generates a shell hook for linking the configuration file to the root
-of the current working directory. The hook will automatically pick up changes
-and re-link as necessary.
-
-```nix
-{
-# ...
-    devShell = pkgs.mkShell {
-        shellHook = nixago.lib.mkShellHook [ preCommit ];
-    };
-# ...
-}
-```
-
-See [the docs][5] for more information.
+See the [quick start][5] for how to get started.
 
 ## Testing
 
@@ -96,7 +56,7 @@ your own, and then:
 [1]: https://nixos.org/
 [2]: https://cuelang.org/
 [3]: https://cuelang.org/docs/integrations/
-[4]: https://pre-commit.com/
-[5]: https://jmgilman.github.io/nixago/
+[4]: https://jmgilman.github.io/nixago/plugins/index.html
+[5]: https://jmgilman.github.io/nixago/quick_start.html
 [6]: https://jmgilman.github.io/nixago/contributing/design
 [7]: https://github.com/jmgilman/nixago/issues

docs/src/introduction.md

@@ -1,12 +1,24 @@
 # Introduction
 
-Nixago is a [flake][1] library that provides functions for generating
-configuration files using [Nix][2] and [Cue][3]. Its primary use is for
-generating configuration files for development tools when using a [nix shell][4]
-for setting up the development environment. You define the configuration data in
-your Nix file and then call out to Nixago to generate it.
+Nixago is a [flake][1] library that aims to simplify managing the various
+configuration files built up at the root of your repositories. Its plugin-based
+approach makes it easy to extend to cover any development tool you may use
+across your projects. It allows your `flake.nix` to serve as the central source
+of truth for configuring your development tools.
+
+Underneath the hood, Nixago uses [Nix][2] and [Cue][3] for generating
+configuration files. It's designed to be used in tandem with a [nix shell][4] to
+dynamically create and manage configuration files in your existing development
+environments. All that's required is defining the configurations in the
+`flake.nix` file at the root of your repository, and Nixago will automatically
+generate shell hooks that can be used to create and manage the files.
+
+Don't see a plugin for your development tool? [Submit a new feature request][5]
+or consider [adding your own][6].
 
 [1]: https://nixos.wiki/wiki/Flakes
 [2]: https://nixos.org/
 [3]: https://cuelang.org/
 [4]: https://nixos.org/manual/nix/stable/command-ref/nix-shell.html
+[5]: https://github.com/jmgilman/nixago/issues/new
+[6]: https://jmgilman.github.io/nixago/contributing/index.html