Update contributing docs. (#5)

Author: vic

README.md

@@ -1,23 +1,16 @@
 # Reproducible builds for Gleam.
 
-```
-nix run github:vic/gleam-nix -- --version
-gleam [0.29.0-rc1](https://github.com/gleam-lang/gleam/commit/9ba0a5f)
-```
+<pre>
+ <code>
+  # If you already have Nix installed, try Gleam right away by using:
+  $ nix shell github:vic/gleam-nix
+  $ gleam --version
+  gleam <a href="https://github.com/gleam-lang/gleam/commit/9ba0a5f">0.29.0-rc1</a>
+ </code>
+</pre>
 
 [![Build history](https://buildstats.info/github/chart/vic/gleam-nix?branch=main)](https://github.com/vic/gleam-nix/actions)
 
-[nix](https://nixos.org/) is a purely functional package manager with
-fully-cacheable, to-the-byte reproducible builds. 
-
-This guide documents how people using the Nix package manager or 
-NixOS systems can easily build every version of Gleam with just
-a single command.
-
-
-<img width="1027" alt="Screen Shot 2021-12-20 at 18 31 47" src="https://user-images.githubusercontent.com/331/146850903-6fd42dda-cef3-4f3b-a720-1916ba91ca22.png">
-
-
 ##### Requirements
 
 For using this guide you'll need `nix` version [2.8](https://discourse.nixos.org/t/nix-2-8-0-released/18714)
@@ -26,45 +19,58 @@ or latter which must have the [`flakes`](https://nixos.wiki/wiki/Flakes) feature
 See [nix quick-install](https://nixos.org/download.html) or the [install-nix tutorial](https://nix.dev/tutorials/install-nix)
 for more in depth instructions.
 
+
 ## Installing Gleam locally (~/.nix-profile)
 
 ```shell
-# This will install gleam from latest commit on main branch.
+# This will install Gleam from latest commit on main branch.
 nix profile install github:vic/gleam-nix --override-input gleam github:gleam-lang/gleam/main
 gleam --help
 ```
 
-## Running Gleam nightly. (or any branch/commit)
+## Installing Gleam on a flake.
 
-The following command runs `gleam --help` on the build from
-the latest commit on `main` branch.
+Using the overlay provided by this flake you can add Gleam to any
+NixOS system or flake-controlled project environment of yours.
 
-```shell
-# The latest commit from Gleam's main branch. (can be a commit hash, tag or branch name)
-nix shell github:vic/gleam-nix --override-input gleam github:gleam-lang/gleam/main -c gleam --help
-```
 
-Gleam maintainers can also use this to try PR experimental features
-from other contributors just by overriding where the Gleam source
-comes from specifying the repository/branch name.
+```nix
+{
+   inputs.gleam-nix.url = "github:vic/gleam-nix";
 
-```shell
-# running gleam to try other people branches:
-nix shell github:vic/gleam-nix --override-input gleam github:<someone>/gleam/<cool-feature> -c gleam --help
+   outputs = { gleam-nix, nixpkgs, ... }:
+     let
+      system = "aarch64-darwin"; # or anything you use.
+      pkgs = import nixpkgs {
+        inherit system;
+        overlays = [ gleam-nix.overlays.default ];
+      };
+     in {
+       packages.${system}.gleam = pkgs.gleam;
+     };
+}
 ```
 
+
 ## Developing Gleam with a Nix environment.
 
 Also, for Gleam developers, using Nix ensures we get the same
 development environment in an instant, all you have to do is
 checkout the Gleam repo and run:
 
 ```shell
-nix develop github:vic/gleam-nix --override-input gleam path:$PWD # -c fish # you might use your preferred shell
+nix develop github:vic/gleam-nix --override-input gleam path:$PWD 
 # open your editor and hack hack hack..
-cargo build # build dependencies are loaded in your shell
-# or 
-nix run github:vic/gleam-nix --override-input gleam path:$PWD -- --help # runs your local `gleam --help`
+cargo run # build dependencies are loaded in your shell
+```
+
+Gleam maintainers can also use this to try PR experimental features
+from other contributors. Just override where the Gleam source
+comes from by specifying the repository/branch name.
+
+```shell
+# running gleam to try other people branches:
+nix shell github:vic/gleam-nix --override-input gleam github:<someone>/gleam/<cool-branch> -c gleam --help
 ```
 
 ## Contributing
@@ -81,7 +87,8 @@ dependencies to build Gleam might have changed. Most of the time, this should
 be fixed by regenerating the Cargo.nix file as instructed bellow.
 
 If you contribute a PR, be sure to also update the latest Gleam version
-known to build at the first section of this document.
+known to build at the first section of this document, so that people can
+use the git history if the need to find the commit that can build older versions.
 
 
 [Nix flakes](https://nixos.wiki/wiki/Flakes) are the secret sauce for nix reproducible builds.
@@ -97,7 +104,7 @@ to regenerate the lock file.
 
 Also run `nix run '.#fmt'` to keep al nix files formatted before sending a PR.
 
-## Regenerating `Cargo.nix`
+#### Regenerating `Cargo.nix`
 
 From time to time the `Cargo.nix` file needs to be re-generated
 by using [cargo2nix](https://github.com/cargo2nix/cargo2nix)
@@ -109,12 +116,12 @@ This is needed when Gleam introduces new dependencies or their versions get upda
 nix run '.#genCargoNix'
 ```
 
-## Updating nixpkgs version
+#### Updating nixpkgs version
 
 By default this package will build using the latest stable nixpkgs release. 
 If you need to update to a most recent release, edit the `nixpkgs.url` line on flake.nix.
 
-## Updating the rust toolchain.
+#### Updating the rust toolchain.
 
 By default this package will build using the latest rust-stable version.
 If you need to update it, edit the `rustChannel` version at flake.nix.