diff --git a/README.md b/README.md
index f6c02ce8d3df9f320f39179735cbbe7f7741a1c4..b1c21f109daa57e46d72396a5f30affba661b927 100644
--- a/README.md
+++ b/README.md
@@ -1,40 +1,90 @@
-# vui
+# Funkwhale design component library
 
-## Project setup
-```
-yarn install
-```
+The Funkwhale design component library is a collection of reusable UI components written in [Vue.js](https://vuejs.org) and [Sass](https://sass-lang.com).
 
-### Compiles and hot-reloads for development
-```
-yarn dev
-```
+Check out [the documentation](https://ui.funkwhale.audio) for information on how each component works and to see a live preview.
 
-### Preview Production build
-```
-yarn preview
-```
+## Contribute to development
 
-### Compiles and minifies for production
-```
-yarn build
-```
+This project welcomes contributions! To get started make sure you have the following:
 
-### Run your unit tests
-```
-yarn test
-```
+1. A design to follow
+2. The use case for the component
 
-### Documentation commands
-```
-yarn docs:dev
-yarn docs:build
-yarn docs:serve
-```
+Join the discussion on [our forum](https://forum.funkwhale.audio) to suggest new components.
 
-### Release a new version
+### Set up your environment
 
-```
+This project uses [Yarn](https://yarnpkg.com/) to manage dependencies and run development scripts. Make sure you have it installed before you start.
+
+1. Install the project dependencies
+
+   ```sh
+   yarn install
+   ```
+
+2. Start a development server to preview your changes in real time
+
+   ```sh
+   yarn dev
+   ```
+
+### Create a production-ready build
+
+You can check how your code looks in production by creating a production-ready build.
+
+1. Compile and minify your code for production
+
+   ```sh
+   yarn build
+   ```
+
+2. Preview the production-ready build
+
+   ```sh
+   yarn preview
+   ```
+
+### Create and run tests
+
+Writing tests for components minimizes the number of bugs that make it to production. This project uses the [Vitest](https://vitest.dev/) framework to run unit tests.
+
+1. Write your test in the [test directory](test/)
+2. Run your unit tests
+
+   ```sh
+   yarn test
+   ```
+
+## Contribute to documentation
+
+Funkwhale UI components should be properly documented before release to make development easier. You should include examples, use cases, and lists of component props to ensure contributors know how to work with components without needing to read the code.
+
+1. Start a development server to preview your changes in real-time
+
+   ```sh
+   yarn docs:dev
+   ```
+
+2. Create a production build of the documentation
+
+   ```sh
+   yarn docs:build
+   ```
+
+3. Serve a production build of the documentation
+
+   ```sh
+   yarn docs:serve
+   ```
+
+## Release a new version
+
+If you want to publish your changes, you need to push a new version of library to NPM.
+
+> **Note**: This project follows the [semantic versioning](https://semver.org/) scheme.
+
+```sh
 yarn version
 git push --tags && git push
 ```
diff --git a/docs/index.md b/docs/index.md
index 8993da6079f08bbcbf7851bfbe185fc2754c16e4..af6d8c4c91a954aba47424bdba7eecd5c53d2732 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,6 +1,6 @@
-# Funkwhale design library
+# Funkwhale design component library
 
-Welcome to the Funkwhale design library. This repository contains a collection of reusable components written in [Vue.js](https://vuejs.org) and [Sass](https://sass-lang.com).
+Welcome to the Funkwhale design component library. This repository contains a collection of reusable components written in [Vue.js](https://vuejs.org) and [Sass](https://sass-lang.com).
 
 <a href="https://design.funkwhale.audio" style="text-decoration: none">
    <fw-card title="Looking for the designs?">