docs: fix links and improve layout

3 files changed, 68 insertions, 36 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9facd98..6208d20 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,7 +12,7 @@ and this project adheres to
 
 - Fixed error message when ignoring file in a directory
 
-## 0.3.0 - 2023-04-20
+## [0.3.0] - 2023-04-20
 
 ### Added
 
@@ -71,3 +71,9 @@ and this project adheres to
 ## [0.1.0] - 2022-11-28
 
 - Initial release
+
+[Unreleased]: https://git.sr.ht/~tobyvin/projectr/log/HEAD
+[0.3.0]: https://git.sr.ht/~tobyvin/projectr/log/v0.3.0
+[0.2.1]: https://git.sr.ht/~tobyvin/projectr/log/v0.2.1
+[0.2.0]: https://git.sr.ht/~tobyvin/projectr/log/v0.2.0
+[0.1.0]: https://git.sr.ht/~tobyvin/projectr/log/v0.1.0
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8cd575a..80ce27e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,27 +2,33 @@
 
 I welcome any contributions in the form of suggestions, bug reports, pull
 requests, and feedback. This document may provide some guidance if you are
-thinking of helping us.
+thinking of contributing.
 
 ## Submitting bug reports and feature requests
 
-Bugs reports and feature requests should be submitted to the [public tracker];
-Any questions can be sent to the [projectr-discuss] mailing list.
+Bugs reports and feature requests should be submitted to
+[~tobyvin/projectr@todo.sr.ht]; Before submitting to the tracker, please
+consider asking about it in [~tobyvin/projectr-discuss@lists.sr.ht].
 
 ## Submitting patches
 
-Patches can be sent to the [projectr-devel]. For help sending patches to this
-list, please consult git-send-email.io, or feel free to ask for help in
-[projectr-discuss].
+Patches can be sent to [~tobyvin/projectr-devel@lists.sr.ht]. Development
+specific questions and discussions should also be submitted there.
+
+For help sending patches, please consult [git-send-email.io], or feel free to
+ask for help in [~tobyvin/projectr-discuss@lists.sr.ht].
 
 ## Conduct
 
 projectr and related community should follow the [Rust Code of Conduct]. For any
-questions or issues related to please submit a post on the [projectr-discuss],
-or feel free to email me directly at [contact@tobyvin.dev].
-
-[contact@tobyvin.dev]: mailto:contact@tobyvin.dev
-[projectr-discuss]: https://lists.sr.ht/~tobyvin/projectr-discuss
-[public tracker]: https://todo.sr.ht/~tobyvin/projectr
-[projectr-devel]: https://lists.sr.ht/~tobyvin/projectr-devel
+questions or issues related to please submit a post on the
+[~tobyvin/projectr-discuss@lists.sr.ht], or feel free to email me directly at
+[tobyv@tobyvin.dev](mailto:tobyv@tobyvin.dev).
+
+[~tobyvin/projectr@todo.sr.ht]: https://todo.sr.ht/~tobyvin/projectr
+[~tobyvin/projectr-discuss@lists.sr.ht]:
+  https://lists.sr.ht/~tobyvin/projectr-discuss
+[~tobyvin/projectr-devel@lists.sr.ht]:
+  https://lists.sr.ht/~tobyvin/projectr-devel
+[git-send-email.io]: https://git-send-email.io
 [Rust Code of Conduct]: https://www.rust-lang.org/policies/code-of-conduct
diff --git a/README.md b/README.md
index 9340d66..32ce00a 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,9 @@
 # Projectr
 
-`projectr` is directory search tool that produces a MRU sorted list of project
-directory paths using provided contexts and filters.
+A contextual, MRU sorted, project finder.
+
+`projectr` is project discovery tool that produces a MRU sorted list of project
+directories using provided contexts and filters.
 
 ## Installation
 
@@ -11,11 +13,10 @@ directory paths using provided contexts and filters.
 cargo install --git=https://git.sr.ht/~tobyvin/projectr
 ```
 
-### Building
-
-Provided you have [Rust installed], projectr can be built using Cargo.
+### Building from source
 
-[Rust installed]: https://www.rust-lang.org/tools/install
+Provided you have [Rust installed](https://www.rust-lang.org/tools/install),
+projectr can be built using Cargo.
 
 ```sh
 $ git clone https://git.sr.ht/~tobyvin/projectr
@@ -25,28 +26,47 @@ $ ./target/release/projectr --version
 projectr 0.2.1
 ```
 
-### Contributing
+## Usage
+
+To list all available options run `projectr -h`.
+
+For a working example, see [tmux-projectr].
+
+## Releases
+
+A list of changes in each release can be found in [CHANGELOG.md].
+
+Subscribe to release announcements on [~tobyvin/projectr-announce@lists.sr.ht].
+
+## Troubleshooting
 
-Anyone can contribute to projectr. Please refer to
-[CONTRIBUTING.md](https://git.sr.ht/~tobyvin/projectr/tree/master/item/CONTRIBUTING.md).
+Ask for support or follow general discussions in
+[~tobyvin/projectr-discuss@lists.sr.ht].
 
-## Resources
+For bug reports and feature requests see [Submitting bug reports and feature
+requests] section in [CONTRIBUTING.md].
 
-Ask for support or follow general discussions on
-[~tobyvin/projectr-discuss@lists.sr.ht](https://lists.sr.ht/~tobyvin/projectr-discuss).
+## Maintainer
 
-Send patches and development related questions to
-[~tobyvin/projectr-devel@lists.sr.ht](https://lists.sr.ht/~tobyvin/projectr-devel).
+[Toby Vincent <tobyv@tobyvin.dev>](tobyvin.dev)
 
-Instructions for preparing a patch are available at
-[git-send-email.io](https://git-send-email.io)
+## Contribution
 
-Subscribe to release announcements on
-[~tobyvin/projectr-announce@lists.sr.ht](https://lists.sr.ht/~tobyvin/projectr-announce)
+Anyone is welcome to contribute to projectr. Please refer to [CONTRIBUTING.md].
 
-Submit _confirmed_ bug reports and _confirmed_ feature requests on
-[https://todo.sr.ht/~tobyvin/projectr](https://todo.sr.ht/~tobyvin/projectr).
+## License
 
-[License](https://git.sr.ht/~tobyvin/projectr/tree/master/item/LICENSE).
+projectr is licensed under the [MIT].
 
-[Change log](https://git.sr.ht/~tobyvin/projectr/tree/master/item/CHANGELOG.md).
+[~tobyvin/projectr-announce@lists.sr.ht]:
+  https://lists.sr.ht/~tobyvin/projectr-announce
+[~tobyvin/projectr-discuss@lists.sr.ht]:
+  https://lists.sr.ht/~tobyvin/projectr-discuss
+[tmux-projectr]:
+  https://git.sr.ht/~tobyvin/projectr/tree/main/item/bin/tmux-projectr
+[MIT]: https://git.sr.ht/~tobyvin/projectr/tree/main/item/LICENSE
+[CHANGELOG.md]: https://git.sr.ht/~tobyvin/projectr/tree/main/item/CHANGELOG.md
+[CONTRIBUTING.md]:
+  https://git.sr.ht/~tobyvin/projectr/tree/main/item/CONTRIBUTING.md
+[Submitting bug reports and feature requests]:
+  https://git.sr.ht/~tobyvin/projectr/tree/main/item/CONTRIBUTING.md#submitting-bug-reports-and-feature-requests