diff --git a/README.md b/README.md
index e249f5386..ed5d5cd99 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# observability-best-practices
+# Observability Best Practices
 
 ## Welcome
 
@@ -6,38 +6,57 @@ This is the source for the [AWS Observability Best Practices site](https://aws-o
 
 ## How to run/develop this site
 
-This site is developed with `mkdocs` which is similar to Hugo with an auto-reload feature. Just save your progress and watch it refresh your browser.
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator. You need to install [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) as a prerequisite.
 
-1) To get started with development, make sure you have a current version of `python` with `pip` installed.
+### Installation
 
-2) Install the following packages:
+```
+cd docusaurus
+$ (yarn | npm ) install
+```
+
+### Local Development
+
+```
+$ yarn start [or] npm run start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
 
 ```
-pip install mkdocs
-pip install mkdocs-material
-pip install pymdown-extensions
+$ yarn build [or] npm run build
 ```
 
-For more details or assistance setting up, see:
-* **mkdocs** - https://www.mkdocs.org/user-guide/installation/#installing-mkdocs
-* **mkdocs-material** - https://squidfunk.github.io/mkdocs-material/getting-started/
-* **pymdown-extensions** - https://facelessuser.github.io/pymdown-extensions/installation/
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
 
-3) Build and run locally on http://127.0.0.1:8000/
+### Deployment
 
+Using SSH with yarn:
 ```
-mkdocs serve
+$ USE_SSH=true yarn deploy 
 ```
 
-If you want to Build and run Japanese content
+Using SSH with npm:
 ```
-mkdocs serve -f mkdocs.ja.yaml
+$ USE_SSH=true  npm run serve
 ```
 
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
+
+
+
 ## Security
 
 See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
 
 ## License
 
-This library is licensed under the MIT-0 License. See the LICENSE file.
+This library is licensed under the MIT-0 License. See the LICENSE file.
\ No newline at end of file
diff --git a/docusaurus/README.md b/docusaurus/README.md
index b2cb48a21..c7db83dbe 100644
--- a/docusaurus/README.md
+++ b/docusaurus/README.md
@@ -12,6 +12,7 @@ You need to install [npm](https://docs.npmjs.com/downloading-and-installing-node
 ### Installation
 
 ```
+cd docusaurus
 $ (yarn | npm ) install
 ```