diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1d707b528d..d57dd63be3 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,57 +1,108 @@
-We love pull requests. Here's a quick guide:
+# Contributing to Faker
 
-1. Fork the repo.
+We are always happy to make improvements to Faker. There are many ways to contribute, from writing tutorials or blog posts, improving the documentation, submitting bug reports and feature requests or writing code which can be incorporated into Faker itself.
 
-2. Run the tests. We only take pull requests with passing tests, and it's great to know that you have a clean slate: `bundle && bundle exec rake`
+Following these guidelines helps to communicate that you respect the time of the developers managing and developing this open source project. In return, they should reciprocate that respect by addressing your issue, assessing changes, and helping you finalize your pull requests.
 
-3. We are using [RuboCop](https://github.com/bbatsov/rubocop) because we love static code analyzers.
-    * Ways to run RuboCop:
-        - `bundle exec rubocop`
-        - `bundle exec rake` would run the test suite and after that it runs the Ruby static code analyzer.
-        - To prevent pushing with test failures or rubocop offenses, see [Setup a custom pre-push git hook](#setup-a-custom-pre-push-git-hook)
 
-4. Please add a test for your change. Only refactoring and documentation changes require no new tests. If you are adding functionality or fixing a bug, we need a test! We use [Minitest](https://github.com/seattlerb/minitest) in this project.
+Have a fix for a problem you've been running into or an idea for a new feature you think would be useful? Here's what you need to do:
 
-5. Make the test pass. Always use `sample`, `shuffle`, and `rand` from the Base class (just like the rest of the code) rather than `Array#sample`, `Array#shuffle` and `Kernel#rand` to preserve the deterministic feature.
+- Fork this repo and clone your fork to somewhere on your machine.
+- [Ensure that you have a working environment](#setting-up-your-environment).
+- Read up on the [architecture of the gem](#architecture), [how to run tests](#running-the-tests), and [the code style we use in this project](#code-style).
+- Cut a new branch and write a failing test for the feature or bugfix you plan on implementing.
+- [Make sure your branch is well managed as you go along](#managing-your-branch).
+- Review the guidelines for [adding new generators](#adding-new-generators), [adding YAML files](#yaml-files), and [YARD docs](#yard-docs).
+- [Refrain from updating the changelog](#a-word-on-the-changelog).
+- Push to your fork and submit a pull request.
+- [Ensure that the test suite passes on GitHub Actions and make any necessary changes to your branch to bring it to green](#continuous-integration).
 
-6. We care about code coverage and use `SimpleCov` to analyze the code and generate test coverage reports. It's possible to check the test coverage by running  `open coverage/index.html`. Please make sure to not decrease our `current % covered` and add appropriate test cases when necessary.
+Although we maintain Faker in our free time, we try to respond to contributions in a timely manner. Once we look at your pull request, we may give you feedback. For instance, we may suggest some changes to make to your code to fit within the project style or discuss alternate ways of addressing the issue in question. Assuming we're happy with everything, we'll then bring your changes into main. Now you're a contributor!
 
-7. When adding a new class, add a new yaml file to `lib/locales/en` rather than adding translations to `lib/locales/en.yml`.  For example, if you add Faker::MyThing, put your translations in `lib/locales/en/my_thing.yml`.  See [the locale README](./lib/locales/en/README.md) for more info.
+## Setting up your environment
 
-8. When removing a method, don't forget to deprecate it. You can `extend Gem::Deprecate` and use the `deprecate` method to accomplish this task.
+Faker requires Ruby version >= 2.7. After forking, and cloning the repo, navigate to the directory, and run:
 
-9. Methods with optional arguments should use keyword rather than positional arguments. An exception to this could be a method that takes only one optional argument, and it's unlikely that that method would ever take more than one optional argument.
 
-10. Push to your fork and submit a pull request.
+```ruby
+bundle install
+```
+
+Run `rake` to ensure the project is all setup. It runs the tests and rubocop. That means you're good to go!
+
+## Architecture
+
+This project follows the typical structure for a gem: code is located in `/lib` and tests are in `/test`. Generators
+
+docs are available in the `/doc` folder.
+
+
+## Running the tests
+
+To run all of the tests, simply run:
+
+```ruby
+bundle exec rake test
+
+```
+
+## Code Style
+
+We use [RuboCop](https://github.com/bbatsov/rubocop) as our static code analyzer.
+
+Please follow these guidelines when adding new code:
+* Use keywords arguments.
+* Two spaces, no tabs.
+* No trailing whitespace. Blank lines should not have any space.
+* Prefer `&&`, `||` over `and`, `or`.
+* `MyClass.my_method(my_argument: my_arg)` not `my_method( my_arg )` or `my_method my_arg`.
+* `a = b` and not `a=b`.
+* In general, follow the conventions you see being used in the source already.
+* Rubocop errors must be resolved for the PR to be approved.
+  * To fix all the offenses automatically with Rubocop's autocorrection tool, run `bundle exec rubocop -A`
+
+There are a few ways to run RuboCop:
+
+```ruby
+`bundle exec rubocop` #-> to only run Rubocop
+
+`bundle exec rake` #-> to run the test suite and rubocop after.
+```
+
+## Managing your branch
+
+- Use well-crafted commit messages and Pull Requests descriptions, providing context if possible.
+
+- Squash "WIP" commits and remove merge commits by rebasing your branch against main. We try to keep our commit history as clean as possible.
+- To prevent pushing with test failures or Rubocop offenses, see [Setup a custom pre-push git hook](#setup-a-custom-pre-push-git-hook).
+
+## A word on the changelog
 
-### Github Flow for contributors and collaborators
+You may also notice that we have a changelog in the form of CHANGELOG.md. You may be tempted to include changes to this in your branch, but don't worry about this — we'll take care of it!
 
-For those of you with commit access, please check out Scott Chacon's blog post about [github flow](http://scottchacon.com/2011/08/31/github-flow.html)
+## Continuous integration
 
-> * Anything in the main branch is deployable
-> * To work on something new, create a descriptively named branch off of main (ie: new-oauth2-scopes)
-> * Commit to that branch locally and regularly push your work to the same named branch on the server
-> * When you need feedback or help, or you think the branch is ready for merging, open a pull request
-> * After someone else has reviewed and signed off on the feature, you can merge it into main
+GitHub Actions will kick in after you push up a branch or open a PR. It takes a few minutes to run a complete build, which you are free to monitor as it progresses. First-time contributors may need to wait until a maintainer approves the build.
 
-If you're reviewing a PR, you should ask yourself:
-> * Does it work as described? A PR should have a great description.
-> * Is it understandable?
-> * Is it well implemented?
-> * Is it well tested?
-> * Is it well documented?
-> * Is it following the structure of the project?
+What happens if the build fails in some way? Don't fear! Click on a failed job and scroll through its output to determine the cause of the failure. You'll want to make changes to your branch and push them up until the entire build is green. It may take a bit of time, but overall it is worth it and it helps us immensely!
 
-### Syntax/Good practices:
+## Adding new generators
 
-#### Documentation
-Include [YARD] style docs for all methods that includes:
+- Don't use `Array#sample`, `Array#shuffle` and `Kernel#rand` on your new generator if you want to randomly pick values. Instead, you should use the methods provided by the Base class: `sample`, `shuffle` and `rand`. The reason is that we want to preserve the deterministic feature of this gem.
+- Please make sure the generator doesn't exist already before opening a PR.
+- Add a new YAML file to `lib/locales/en` rather than adding translations to `lib/locales/en.yml`. For example, if you add `Faker::MyThing`, put your translations in `lib/locales/en/my_thing.yml`. See [the locale README](./lib/locales/en/README.md) for more info.
+
+### YARD docs
+
+- Include [YARD] style docs for all methods that includes:
 - A short description of what the method generates
 - Descriptions for all params (`@param`)
 - The return type (`@return`)
 - At least one example of the output (`@example`)
 - The version that the method was added (`@faker.version`)
-  - Set as `next` for new methods or methods with new features 
+  - Set as `next` for new methods or methods with new features
+
+Here is an example:
 
 ```ruby
 ##
@@ -71,19 +122,27 @@ def alpha(number: 32)
 end
 ```
 
-#### Code Styles
-Please follow these guidelines when adding new code:
-* Two spaces, no tabs.
-* No trailing whitespace. Blank lines should not have any space.
-* Prefer `&&`, `||` over `and`, `or`.
-* `MyClass.my_method(my_arg)` not `my_method( my_arg )` or `my_method my_arg`.
-* `a = b` and not `a=b`.
-* In general, follow the conventions you see used in the source already.
-* **ALL SHALL OBEY THE RUBOCOP**
+[YARD]: (https://www.rubydoc.info/gems/yard/file/README.md)
+
+## Removing generators
+
+To remove a generator or any other public method, deprecate them first. We use the `Gem::Deprecate`[https://ruby-doc.org/stdlib-3.1.0/libdoc/rubygems/rdoc/Gem/Deprecate.html].
+
+To deprecate a method/argument, add `extend Gem::Deprecate` to the top of the class, and use the `deprecate` method.
+
+## YAML files
+
+Please use dash syntax for YAML arrays. The dash syntax faciliates code reviews by making it eaiser to see what items were added or removed from the lists.
+
+Here is an example:
 
-#### YAML
-Please use dash syntax for yaml arrays:
 ```Yaml
+# this is preferred
+a_things:
+  - small_thing
+  - big_thing
+  - other_thing
+
 # instead of these
 b_things: [small_thing, big_thing, other_thing]
 c_things: [
@@ -91,25 +150,19 @@ c_things: [
   big_thing,
   other_thing,
 ]
-
-# this is preferred
-a_things:
-  - small_thing
-  - big_thing
-  - other_thing
 ```
-- If in doubt, `bundle exec rake reformat_yaml['lib/path/to/file.yml']`
 
-### Tips
+When in doubt, run `bundle exec rake reformat_yaml['lib/path/to/file.yml']` to reformat your YAML file.
+
+## Tips
 
 * Use the `rake console` task to start a session with Faker loaded.
-* Use `bundle exec yard server -r` to launch the YARD Doc server
+* Use `bundle exec yard server -r` to launch the YARD Doc server.
 
-[YARD]: (https://www.rubydoc.info/gems/yard/file/README.md)
+## Setup a custom pre-push git hook
 
-### Setup a custom pre-push git hook
+There is a custom git hooks pre-push file. Before the push occurs, it runs the tests and Rubocop. If there are any tests failures, or Rubocop offenses, the push is aborted.
 
-There is a custom git hooks pre-push file. Before the push occurs, it runs the tests and rubocop. If there are any tests failures, or Rubocop offenses, the push is aborted.
 
 To set up:
 - Copy the file `pre-push.sample` located in the `custom-hooks` folder.
@@ -120,4 +173,4 @@ To skip this hook for any push, add `--no-verify` to the end of the command:
 
 `git push --no-verify <remote_name> <branch_name>`
 
-To disable this hook completely: remove the file `.git/hooks/pre-push`
+To disable this hook completely: remove the file `.git/hooks/pre-push`.
diff --git a/MAINTAINING.md b/MAINTAINING.md
new file mode 100644
index 0000000000..57f0d46dac
--- /dev/null
+++ b/MAINTAINING.md
@@ -0,0 +1,21 @@
+### Maintaining Faker
+
+As maintainers of the gem, this is our guide. Most of the steps and guidelines in the Contributing document apply here, including how to set up your environment, write code to fit the code style, run tests, craft commits and manage branches. Beyond this, this document provides some details that would be too low-level for contributors.
+
+If you're reviewing a PR, you should ask yourself:
+> * Does it work as described? A PR should have a great description.
+> * Is it understandable?
+> * Is it well implemented?
+> * Is it well tested?
+> * Is it well documented?
+> * Is it following the structure of the project?
+
+# TODO
+
+- Communication
+- Workflow
+- Versioning
+- Issuing new releases
+- Updating the Changelog
+- Granting Rubygems access
+- Labels
\ No newline at end of file
diff --git a/README.md b/README.md
index cb007b3a91..6dc25038c5 100644
--- a/README.md
+++ b/README.md
@@ -7,21 +7,33 @@
 [![Test Coverage](https://api.codeclimate.com/v1/badges/ef54c7f9df86e965d64b/test_coverage)](https://codeclimate.com/github/stympy/faker/test_coverage)
 [![Maintainability](https://api.codeclimate.com/v1/badges/ef54c7f9df86e965d64b/maintainability)](https://codeclimate.com/github/stympy/faker/maintainability)
 
-This gem is a port of [Perl's Data::Faker library](https://metacpan.org/pod/Data::Faker) that generates fake data.
+Faker is a port of [Perl's Data::Faker library](https://metacpan.org/pod/Data::Faker).
+It's a library for generating fake data such as names, addresses, and phone numbers.
 
-It comes in very handy for taking screenshots (taking screenshots for my
-project, [Catch the Best](http://catchthebest.com/) was the original impetus
-for the creation of this gem), having real-looking test data, and having your
-database populated with more than one or two records while you're doing
-development.
+Faker helps you generate realistic test data, and populate your
+database with more than a couple of records while you're doing development.
+
+It comes in very handy for taking screenshots (taking screenshots for a personal project)
+and it was the original impetus for the creation of this gem).
+
+## Quick links
+
+- 📖 **[Read the documentation for the latest version][rubydocs].**
+- 📢 **[See what's changed in recent versions][changelog].**
+
+[rubydocs]: https://www.rubydoc.info/gems/faker/
+[changelog]: CHANGELOG.md
+
+## Table of Contents
 
 - [Faker](#faker)
-    - [NOTE](#note)
-  - [Installing](#installing)
+    - [Notes](#notes)
+  - [Getting Started](#getting-started)
   - [Usage](#usage)
     - [CLI](#cli)
     - [Ensuring unique values](#ensuring-unique-values)
     - [Deterministic Random](#deterministic-random)
+    - [Customization](#customization)
   - [Generators](#generators)
     - [Default](#default)
     - [Blockchain](#blockchain)
@@ -35,45 +47,87 @@ development.
     - [Quotes](#quotes)
     - [Sports](#sports)
     - [Tv Shows](#tv-shows)
-  - [Customization](#customization)
   - [Contributing](#contributing)
-  - [Contact](#contact)
+  - [Versioning](#versioning)
+  - [Team](#team)
   - [License](#license)
 
-### NOTE
+### Notes
+
 * While Faker generates data at random, returned values are not guaranteed to be unique by default.
-  You must explicitly specify when you require unique values, see [details](#ensuring-unique-values).
-  Values also can be deterministic if you use the deterministic feature, see [details](#deterministic-random)
-* Minitest and Faker >= 2.22 users might need to add the following to the `test_helper.rb` or `rails_helper.rb` file:
-  `Faker::Config.random = Random.new`. See [Issue #2534](https://github.com/faker-ruby/faker/issues/2534) for more details.
+  To explicitly specify when you require unique values, see [Ensuring Unique Values](#ensuring-unique-values).
+  Values also can be deterministic if you use the deterministic feature, see [Deterministic Random](#deterministic-random)
 * This is the `main` branch of Faker and may contain changes that are not yet released.
-  Please refer the README of your version for the available methods.
-  List of all versions is [available here](https://github.com/stympy/faker/releases).
+  Please refer to the README of your version for the available methods.
+  The list of all versions is [available here](https://github.com/stympy/faker/releases).
 
-## Installing
-```bash
-gem install faker
-```
-Note: if you are getting a `uninitialized constant Faker::[some_class]` error, your version of the gem is behind the one documented here. To make sure that your gem is the one documented here, change the line in your Gemfile to:
+## Getting Started
+
+Start by including `faker` in your Gemfile:
 
 ```ruby
-gem 'faker', :git => 'https://github.com/faker-ruby/faker.git', :branch => 'main'
+gem 'faker'
 ```
 
+Then run `bundle install`.
+
 ## Usage
+
+Here are some examples of how to use Faker:
+
 ```ruby
 require 'faker'
 
 Faker::Name.name      #=> "Christophe Bartell"
 
-Faker::Internet.email #=> "kirsten.greenholt@corkeryfisher.info"
+Faker::Address.full_address #=> "5479 William Way, East Sonnyhaven, LA 63637"
+
+Faker::Markdown.emphasis #=> "Quo qui aperiam. Amet corrupti distinctio. Sit quia *dolor.*"
+
+Faker::TvShows::RuPaul.queen #=> "Violet Chachki"
+
+Faker::Alphanumeric.alpha(number: 10) #=> "zlvubkrwga"
+
+Faker::ProgrammingLanguage.name #=> "Ruby"
 ```
 
-### CLI
+For a complete list of the generators, see [Generators](#generators).
+
+#### A note about the Generators versions
+
+If you get a `uninitialized constant Faker::[some_class]` error, your version of
+the gem is behind main.
+
+To make sure that your gem is the one
+documented here, change the line in your Gemfile to:
+
+```ruby
+gem 'faker', :git => 'https://github.com/faker-ruby/faker.git', :branch => 'main'
+```
+
+The generators have the `@faker.version` tag on top of their implementation.
+From the tags, you can identify the version the generator was added:
+
+```
+# Faker::TvShows::ParksAndRec.character
+
+# @faker.version 1.9.0
+def character
+  fetch('parks_and_rec.characters')
+end
+```
+
+### Faker-bot CLI (command-line interface)
+
+[faker-bot](https://github.com/faker-ruby/faker-bot) is a tool to make it easier
+to pick the right Faker methods to generate the fake data you need.
+
 Instructions are available in the [faker-bot README](https://github.com/faker-ruby/faker-bot).
 
 ### Ensuring unique values
-Prefix your method call with `unique`. For example:
+
+To ensure Faker generates unique values, prefix your method call with `unique`:
+
 ```ruby
 Faker::Name.unique.name # This will return a unique name every time it is called
 ```
@@ -82,6 +136,7 @@ If too many unique values are requested from a generator that has a limited
 number of potential values, a `Faker::UniqueGenerator::RetryLimitExceeded`
 exception may be raised. It is possible to clear the record of unique values
 that have been returned, for example between tests.
+
 ```ruby
 Faker::Name.unique.clear # Clears used values for Faker::Name
 Faker::UniqueGenerator.clear # Clears used values for all generators
@@ -100,7 +155,9 @@ Faker::Lorem.unique.exclude :string, [number: 6], %w[azerty wxcvbn]
 ```
 
 ### Deterministic Random
-Faker supports seeding of its pseudo-random number generator (PRNG) to provide deterministic output of repeated method calls.
+
+Faker supports seeding of its pseudo-random number generator (PRNG)
+to provide deterministic output of repeated method calls.
 
 ```ruby
 Faker::Config.random = Random.new(42)
@@ -115,14 +172,49 @@ Faker::Config.random.seed #=> 185180369676275068918401850258677722187
 Faker::Company.bs #=> "cultivate viral synergies"
 ```
 
+### Customization
+
+You may want Faker to print information depending on your location in the world.
+To assist you in this, Faker uses the `I18n` gem to store strings and formats to
+represent the names and postal codes of the area of your choosing.
+
+Just set the locale you want as shown below, and Faker will take care of the rest.
+
+```ruby
+Faker::Config.locale = 'es'
+# or
+Faker::Config.locale = :es
+```
+
+Note: Overriding the default locale might not be thread-safe. See [Locale setting can be ignored #2563](https://github.com/faker-ruby/faker/issues/2563) for more details.
+
+To override Faker's locales, 
+check out the [locales README](lib/locales/README.md).
+
+### Minitest and Faker >= 2.22
+
+To prevent Faker (version >= 2.22) from generating duplicate values when using Minitest,
+you might need to add the following to the `test_helper.rb` or `rails_helper.rb` file:
+
+```ruby
+  Faker::Config.random = Random.new
+```
+
+See [Issue #2534](https://github.com/faker-ruby/faker/issues/2534) for more details.
+
 ## Generators
+
+This is the full list of generators available with this gem. If you need details about any of them, make sure to consult the documentation.
+
 **NOTE: Some of the generators below aren't released yet. If you want to use them, change the line in your gemfile to:**
 
 ```ruby
 gem 'faker', :git => 'https://github.com/faker-ruby/faker.git', :branch => 'main'
 ```
 
-### Default
+<details>
+  <summary>Default</summary>
+
   - [Faker::Address](doc/default/address.md)
   - [Faker::Alphanumeric](doc/default/alphanumeric.md)
   - [Faker::Ancient](doc/default/ancient.md)
@@ -221,31 +313,46 @@ gem 'faker', :git => 'https://github.com/faker-ruby/faker.git', :branch => 'main
   - [Faker::Verbs](doc/default/verbs.md)
   - [Faker::VulnerabilityIdentifier](doc/default/vulnerability_identifier.md)
   - [Faker::WorldCup](doc/default/world_cup.md)
+</details>
+
+<details>
+  <summary>Blockchain</summary>
 
-### Blockchain
   - [Faker::Blockchain::Aeternity](doc/blockchain/aeternity.md)
   - [Faker::Blockchain::Bitcoin](doc/blockchain/bitcoin.md)
   - [Faker::Blockchain::Ethereum](doc/blockchain/ethereum.md)
   - [Faker::Blockchain::Tezos](doc/blockchain/tezos.md)
+</details>
+
+<details>
+  <summary>Books</summary>
 
-### Books
   - [Faker::Book](doc/books/book.md)
   - [Faker::Books::CultureSeries](doc/books/culture_series.md)
   - [Faker::Books::Dune](doc/books/dune.md)
   - [Faker::Books::Lovecraft](doc/books/lovecraft.md)
   - [Faker::Books::TheKingkillerChronicle](doc/books/the_kingkiller_chronicle.md)
+</details>
+
+<details>
+  <summary>Fantasy</summary>
 
-### Fantasy
   - [Faker::Fantasy::Tolkien](doc/fantasy/tolkien.md)
+</details>
+
+<details>
+  <summary>Creature</summary>
 
-### Creature
   - [Faker::Creature::Animal](doc/creature/animal.md)
   - [Faker::Creature::Bird](doc/creature/bird.md)
   - [Faker::Creature::Cat](doc/creature/cat.md)
   - [Faker::Creature::Dog](doc/creature/dog.md)
   - [Faker::Creature::Horse](doc/creature/horse.md)
+</details>
+
+<details>
+  <summary>Games</summary>
 
-### Games
   - [Faker::Game](doc/games/game.md)
   - [Faker::Games::ClashOfClans](doc/games/clash_of_clans.md)
   - [Faker::Games::DnD](doc/games/dnd.md)
@@ -269,8 +376,11 @@ gem 'faker', :git => 'https://github.com/faker-ruby/faker.git', :branch => 'main
   - [Faker::Games::Witcher](doc/games/witcher.md)
   - [Faker::Games::WorldOfWarcraft](doc/games/world_of_warcraft.md)
   - [Faker::Games::Zelda](doc/games/zelda.md)
+</details>
+
+<details>
+  <summary>Japanese Media</summary>
 
-### Japanese Media
   - [Faker::JapaneseMedia::CowboyBebop](doc/japanese_media/cowboy_bebop.md)
   - [Faker::JapaneseMedia::DragonBall](doc/japanese_media/dragon_ball.md)
   - [Faker::JapaneseMedia::OnePiece](doc/japanese_media/one_piece.md)
@@ -280,8 +390,11 @@ gem 'faker', :git => 'https://github.com/faker-ruby/faker.git', :branch => 'main
   - [Faker::JapaneseMedia::Doraemon](doc/japanese_media/doraemon.md)
   - [Faker::JapaneseMedia::Conan](doc/japanese_media/conan.md)
   - [Faker::JapaneseMedia::FmaBrotherhood](doc/japanese_media/fullmetal_alchemist_brotherhood.md)
+</details>
+
+<details>
+  <summary>Movies</summary>
 
-### Movies
   - [Faker::Movie](doc/movies/movie.md)
   - [Faker::Movies::BackToTheFuture](doc/movies/back_to_the_future.md)
   - [Faker::Movies::Departed](doc/movies/departed.md)
@@ -296,8 +409,11 @@ gem 'faker', :git => 'https://github.com/faker-ruby/faker.git', :branch => 'main
   - [Faker::Movies::StarWars](doc/movies/star_wars.md)
   - [Faker::Movies::TRON](doc/movies/tron.md)
   - [Faker::Movies::VForVendetta](doc/movies/v_for_vendetta.md)
+</details>
+
+<details>
+  <summary>Music</summary>
 
-### Music
   - [Faker::Music](doc/music/music.md)
   - [Faker::Music::GratefulDead](doc/music/grateful_dead.md)
   - [Faker::Music::Hiphop](doc/music/hiphop.md)
@@ -308,22 +424,30 @@ gem 'faker', :git => 'https://github.com/faker-ruby/faker.git', :branch => 'main
   - [Faker::Music::RockBand](doc/music/rock_band.md)
   - [Faker::Music::Rush](doc/music/rush.md)
   - [Faker::Music::UmphreysMcgee](doc/music/umphreys_mcgee.md)
+</details>
+
+<details>
+  <summary>Quotes</summary>
 
-### Quotes
   - [Faker::Quote](doc/quotes/quote.md)
   - [Faker::Quotes::Chiquito](doc/quotes/chiquito.md)
   - [Faker::Quotes::Rajnikanth](doc/quotes/rajnikanth.md)
   - [Faker::Quotes::Shakespeare](doc/quotes/shakespeare.md)
+</details>
 
+<details>
+  <summary>Sports</summary>
 
-### Sports
   - [Faker::Sports](doc/sports/sports.md)
   - [Faker::Sports::Basketball](doc/sports/basketball.md)
   - [Faker::Sports::Football](doc/sports/football.md)
   - [Faker::Sports::Mountaineering](doc/sports/mountaineering.md)
   - [Faker::Sports::Volleyball](doc/sports/volleyball.md)
+</details>
+
+<details>
+  <summary>Tv Shows</summary>
 
-### Tv Shows
   - [Faker::TvShows::AquaTeenHungerForce](doc/tv_shows/aqua_teen_hunger_force.md)
   - [Faker::TvShows::BigBangTheory](doc/tv_shows/big_bang_theory.md)
   - [Faker::TvShows::BojackHorseman](doc/tv_shows/bojack_horseman.md)
@@ -360,59 +484,25 @@ gem 'faker', :git => 'https://github.com/faker-ruby/faker.git', :branch => 'main
   - [Faker::TvShows::TheThickOfIt](doc/tv_shows/the_thick_of_it.md)
   - [Faker::TvShows::TwinPeaks](doc/tv_shows/twin_peaks.md)
   - [Faker::TvShows::VentureBros](doc/tv_shows/venture_bros.md)
+</details>
 
-## Customization
-You may want Faker to print information depending on your location in the world.
-To assist you in this, Faker uses I18n gem to store strings and formats to
-represent the names and postal codes of the area of your choosing.
-Just set the locale you want as shown below, and Faker will take care of the rest.
+## Contributing
 
-```ruby
-Faker::Config.locale = 'es'
-# or
-Faker::Config.locale = :es
-```
+If you have problems, please create a [GitHub Issue](/.github/ISSUE_TEMPLATE/bug-report.md).
 
-If your locale doesn't already exist, create it in the `lib/locales` directory
-and you can then override or add elements to suit your needs. See more about how to
-use locales [here](lib/locales/README.md)
-
-```yaml
-en-au-ocker:
-  faker:
-    name:
-      # Existing faker field, new data
-      first_name:
-        - Charlotte
-        - Ava
-        - Chloe
-        - Emily
-
-      # New faker fields
-      ocker_first_name:
-        - Bazza
-        - Bluey
-        - Davo
-        - Johno
-        - Shano
-        - Shazza
-      region:
-        - South East Queensland
-        - Wide Bay Burnett
-        - Margaret River
-        - Port Pirie
-        - Gippsland
-        - Elizabeth
-        - Barossa
-```
+Take a look at the [Contributing](CONTRIBUTING.md) document for
+instructions on setting up the repo on your machine, understanding the codebase,
+and creating a good pull request.
 
-## Contributing
-See [CONTRIBUTING.md](https://github.com/stympy/faker/blob/main/CONTRIBUTING.md).
+There is a [Discord channel](https://discord.gg/RMumTwB) to discuss anything
+regarding improvements or feature requests.
 
-## Contact
-Comments and feedback are welcome. Send an email to Benjamin Curtis via the [google group](http://groups.google.com/group/ruby-faker).
+Thank you, contributors!
 
-You can also join our [discord channel](https://discord.gg/RMumTwB) to discuss anything regarding improvements or feature requests.
+## Versioning
+
+Faker follows Semantic Versioning 2.0 as defined at https://semver.org.
 
 ## License
+
 This code is free to use under the terms of the MIT license.