diff --git a/docs/assets/docs/docs-contribution-keyboard.jpg b/docs/assets/docs/docs-contribution-keyboard.jpg
new file mode 100644
index 0000000000000..0c2423d4ef386
Binary files /dev/null and b/docs/assets/docs/docs-contribution-keyboard.jpg differ
diff --git a/docs/assets/docs/docs.jpg b/docs/assets/docs/docs.jpg
new file mode 100644
index 0000000000000..2349fd159a996
Binary files /dev/null and b/docs/assets/docs/docs.jpg differ
diff --git a/docs/assets/docs/docusaurus.jpg b/docs/assets/docs/docusaurus.jpg
new file mode 100644
index 0000000000000..f7427e5a85feb
Binary files /dev/null and b/docs/assets/docs/docusaurus.jpg differ
diff --git a/docs/assets/docs/science-kid.jpg b/docs/assets/docs/science-kid.jpg
new file mode 100644
index 0000000000000..c45f5c3a3724e
Binary files /dev/null and b/docs/assets/docs/science-kid.jpg differ
diff --git a/docs/assets/docs/useless_example.jpg b/docs/assets/docs/useless_example.jpg
new file mode 100644
index 0000000000000..2c967de789e15
Binary files /dev/null and b/docs/assets/docs/useless_example.jpg differ
diff --git a/docs/docusaurus/contributing_to_docs.md b/docs/docusaurus/contributing_to_docs.md
new file mode 100644
index 0000000000000..76cc8abcd5128
--- /dev/null
+++ b/docs/docusaurus/contributing_to_docs.md
@@ -0,0 +1,26 @@
+# Contributions to docs
+
+![hide easter egg text for images in these thingies](../assets/docs/docs-contribution-keyboard.jpg)
+
+## Did you just learn something?!
+- maybe write a doc for it!
+
+## Where to put stuff
+- Try and utilize existing folder structure
+- If it fits in an existing category: great!
+- If it doesn't add it to `/docs/` top level
+  - If it makes sense to make a new category with other top level make a new directory
+- **images** and other assets live in `/docs/assets/`
+- New folders **need at least 2 markdown files** for docusarus to recognise the folder in the sidebar
+
+## Testing your changes locally
+
+[more in depth local change guide here](locally_testing_docusaurus.md)
+- You can see what the docs website will look like locally try:
+```bash
+cd docusaurus
+yarn build && yarn serve
+# press control-c to exit the server
+```
+- if you change **anything at all** 
+  - Your changes will not show up on the website until you re-run `yarn build && yarn serve`
diff --git a/docs/docusaurus/deploying_and_reverting_docs.md b/docs/docusaurus/deploying_and_reverting_docs.md
new file mode 100644
index 0000000000000..801a8256004fd
--- /dev/null
+++ b/docs/docusaurus/deploying_and_reverting_docs.md
@@ -0,0 +1,36 @@
+# Deploying and Reverting Docs
+
+![docs are fun](../assets/docs/docs.jpg)
+
+Docusaurus has a strange deployment pattern.  Luckily that pattern is abstracted away from you.
+
+If you were looking for the contribution guide [check this doc out](contributing_to_docs.md)
+
+Docs will deploy from whatever branch you are in. You will probably want to deploy from master, but that is at your discretion.
+
+[This is the deployment tool](https://github.com/airbytehq/airbyte/blob/master/tools/bin/deploy_docusaurus)
+You will need a github ssh key, the tool will properly tell you if you don't have one though
+
+At it's simplest just open the airbyte repo and run `./tools/bin/deploy_docusaurus`
+
+A typical deployment will look like this
+
+
+```bash
+cd airbyte
+# or cd airbyte-cloud  
+git checkout master
+git pull
+./tools/bin/deploy_docusaurus
+```
+
+If docs has a problem this procedure will work the same on older branches.
+The push to production is a force push so collisions are unlikely
+
+If you want to revert/rollback it will look something like this
+
+```bash
+cd airbyte
+git checkout $SOME_OLDER_BRANCH
+./tools/bin/deploy_docusaurus
+```
diff --git a/docs/docusaurus/docusaurus_settings.md b/docs/docusaurus/docusaurus_settings.md
new file mode 100644
index 0000000000000..ba79876da0109
--- /dev/null
+++ b/docs/docusaurus/docusaurus_settings.md
@@ -0,0 +1,40 @@
+# Docusaurus Settings
+
+Docusaurus is the tool that generates the website that hosts docs in cloud and OSS.
+Here are some quick relevant guides using docusaurus at Airbyte.
+
+### I want to change the sidebar
+- **OSS**: sidebar is generated in a [JSON blob here](https://github.com/airbytehq/airbyte/blob/master/docusaurus/sidebars.js)
+- **OSS**: Here is a guide to the [JSON blob structure](https://docusaurus.io/docs/sidebar/items)
+- **Cloud**: sidebar is autogenerated
+  - folders will become dropdown items
+  - if there is a `README.md` in the folder
+    - it will be the default view
+    - the first `# heading` will be the folder title
+  - if there is not a `README.md` in the folder name of folder will be the drop down name
+
+### But how do I change the links on top?
+- go to one of these config files
+  - [OSS file location](https://github.com/airbytehq/airbyte/blob/master/docusaurus/docusaurus.config.js)
+  - [Cloud file location](https://github.com/airbytehq/airbyte-cloud/blob/master/docusaurus/docusaurus.config.js#L64)
+- Copy an existing JSON object like this but change the values a bit so people don't think you copied my homework
+```js
+{
+    href: 'https://theuselessweb.com',
+    position: 'left',
+    label: 'A collection of useless websites',
+},
+```
+![its a funny website](../assets/docs/useless_example.jpg)
+- test locally [following this guide](locally_testing_docusaurus.md)
+
+
+### Updating docusaurus
+
+For security and an occasional cool features you may want to update docusaurus.  From time to time docusaurus will suggest you do just that.
+It is a reasonable decision to copy the update command docusaurus suggests.  It should look something like this:
+```bash
+yarn upgrade @docusaurus/core@latest @docusaurus/plugin-google-gtag@latest @docusaurus/preset-classic@latest
+```
+Keep in mind this won't update dependencies.  The upside is that the dependencies probably won't break.  
+The downside is that they probably also contain known security vulnerabilities.
diff --git a/docs/docusaurus/locally_testing_docusaurus.md b/docs/docusaurus/locally_testing_docusaurus.md
new file mode 100644
index 0000000000000..8e3f4a0a24347
--- /dev/null
+++ b/docs/docusaurus/locally_testing_docusaurus.md
@@ -0,0 +1,32 @@
+# Locally testing your changes
+
+![testing is fun and games until it blows up](../assets/docs/science-kid.jpg)
+
+You can test any change you make to see how it will look in production
+
+The processes are almost identical from local testing to production so 
+you can have a high degree of confidence in the results
+
+```bash
+# navigate to docusaurus
+cd airbyte-cloud/docusaurus
+# install the packages to run docusaurus
+yarn install
+# compile the current state of airbyte-cloud/docs
+# into the website and serve it at http://localhost:3000
+yarn build && yarn serve
+# control-c sends the SIGTERM command to the running process
+# this is a common way to exit running shell applications
+# to exit the running server use control-c
+```
+
+- If you encounter a build error there may be multiple causes 
+but usually this is due to a broken link:
+    - fix your broken links and the build should work
+- look at the changes you made locally, 
+if they look great commit and add a funny picture to the PR for karma (technically optional)
+
+**important note**
+if you run `yarn build && yarn serve` and make changes after that you will need
+to exit the server using `control-c` from the command line and then running the 
+command `yarn build && yarn serve` again to see your new changes
diff --git a/docs/docusaurus/readme.md b/docs/docusaurus/readme.md
new file mode 100644
index 0000000000000..400f248097e6c
--- /dev/null
+++ b/docs/docusaurus/readme.md
@@ -0,0 +1,10 @@
+# Docusaurus / Docs
+
+![isn't he cute?](../assets/docs/docusaurus.jpg)
+
+Guides on how to use docusaurus and docs in airbyte
+
+the usages between here and OSS are nearly identical
+
+OSS uses a hand writted JSON blob for sidebar structure, 
+otherwise there is almost 100% overlap
diff --git a/docusaurus/sidebars.js b/docusaurus/sidebars.js
index 52945dbfdfb72..41325b247a1ff 100644
--- a/docusaurus/sidebars.js
+++ b/docusaurus/sidebars.js
@@ -44,6 +44,28 @@ module.exports = {
         },
       ]
     },
+    {
+      type: 'category',
+      label: 'Contributing to Airbyte Docs',
+      items: [
+        {
+          type: 'doc',
+          id: "docusaurus/contributing_to_docs",
+        },
+        {
+          type: 'doc',
+          id: "docusaurus/deploying_and_reverting_docs",
+        },
+        {
+          type: 'doc',
+          id: "docusaurus/locally_testing_docusaurus",
+        },
+        {
+          type: 'doc',
+          id: "docusaurus/readme",
+        },
+      ]
+    },
     {
       type: 'category',
       label: 'Deploying Airbyte Open Source',