Docusaurus: README update

docusaurus/README.md

@@ -1,14 +1,14 @@
 # Documentation and Docusaurus
 
-We use [docusaurus](https://docusaurus.io) for consistent process, in `Airbyte` **no website is generated**.
-Functionally this is a very fancy **linter**
-
-Running the build process will **check for broken links**, please read the output and address
-any broken links that you are able to do.
+We use [Docusaurus](https://docusaurus.io) to build Airbyte
+[documentation site](https://docs.airbyte.io) from documentation source files in Markdown, and lint
+the source files. We host the resulting docs site on Vercel. It deploys automatically when any
+changes get merged to `master`.
 
 ## Installation
 
-For consistency across other Airbyte projects we use yarn (A Javascript based software package manager)
+For consistency across other Airbyte projects we use yarn (A Javascript based software package
+manager).
 
 ```bash
 brew install yarn
@@ -18,26 +18,63 @@ yarn install
 yarn build
 ```
 
-At this point you will see any broken links that docusaurus was able to find.
+`yarn build` will build Docusaurus site in `docusaurus/build` directory.
 
 ## Developing Locally
 
+If you want to make changes to the documentation, you can run docusaurus locally in a way that would
+listen to any source docs changes and live-reload them:
+
 ```bash
 yarn start # any changes will automatically be reflected in your browser!
 ```
 
-## Making Changes
+All the content for docs.airbyte.com lives in the `/docs` directory in this repo. All files are
+markdown. Make changes or add new files, and you should see them in your browser!
+
+## Changing Navigation Structure
+
+If you have created any new files, be sure to add them manually to the table of contents found here
+in [`sidebars.js`](https://github.com/airbytehq/airbyte/blob/master/docusaurus/sidebars.js)
+
+## Contributing
+
+We welcome documentation updates! If you'd like to contribute a change, please make sure to:
 
-All the content for docs.airbyte.com lives in the `/docs` directory in this repo. All files are markdown. Make changes or add new files, and you should see them in your browser!
+- Run `yarn build` and check that all build steps are successful.
+- Push your changes into a pull request, and follow the PR template instructions.
 
-If you have created any new files, be sure to add them manually to the table of contents found here in this [file](https://github.com/airbytehq/airbyte/blob/master/docusaurus/sidebars.js)
+When you make a pull request, Vercel will automatically build a test instance of the full docs site
+and link it in the pull request for review.
 
-## Plugin Client Redirects
+### Checking for broken links
+
+Airbyte docs site checks link with Docusaurus at build time, and with an additional GitHub action
+periodically:
+
+- Running the build process will **check for broken links**, please read the output and address any
+  broken links that you are able to do.
+- [This GitHub Action](https://github.com/airbytehq/airbyte/blob/master/.github/workflows/doc-link-check.yml)
+  checks all links on Airbyte production docs site, and tells us if any of them are broken.
+
+> [!NOTE] Docusaurus links checker only checks _relative_ links, and assumes that absolute links are
+> fine. For that reason, if you're linking to another Airbyte documentation page, make it a relative
+> link. I.e. `[link](/connector-development/overview.md)` instead of
+> `[link](https://docs.airbyte.com/connector-development/)`. That way, if your link breaks in the
+> future, it will be caught with `yarn build`.
+
+## Docusaurus Plusings We Use
+
+### Plugin Client Redirects
 
 A silly name, but a useful plugin that adds redirect functionality to docusaurus
 [Official documentation here](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-client-redirects)
 
-You will need to edit [this docusaurus file](https://github.com/airbytehq/airbyte/blob/master/docusaurus/docusaurus.config.js#L22)
+If you're proposing to move an existing documentation file or change it's name, please setup a
+redirect rule.
+
+You will need to edit
+[this docusaurus file](https://github.com/airbytehq/airbyte/blob/master/docusaurus/docusaurus.config.js#L22)
 
 You will see a commented section the reads something like this
 
@@ -48,13 +85,18 @@ You will see a commented section the reads something like this
 //                        },
 ```
 
-Copy this section, replace the values, and [test it locally](locally_testing_docusaurus.md) by going to the
-path you created a redirect for and checked to see that the address changes to your new one.
+Copy this section, replace the values, and [test it locally](locally_testing_docusaurus.md) by going
+to the path you created a redirect for and checked to see that the address changes to your new one.
 
 _Note:_ Your path \*_needs_ a leading slash `/` to work
 
 ## Deploying Docs
 
-We use Github Pages for hosting this docs website, and [Docusaurus](https://docusaurus.io/) as the docs framework. Any change to the `/docs` directory you make is deployed when you merge to your PR to the master branch automagically!
+Airbyte docs live on Vercel. Any change to the `/docs` directory you make is deployed when you merge
+to your PR to the master branch automagically!
 
-The source code for the docs lives in the [airbyte monorepo's `docs/` directory](https://github.com/airbytehq/airbyte/tree/master/docs). Any changes to the `/docs` directory will be tested automatically in your PR. Be sure that you wait for the tests to pass before merging! If there are CI problems publishing your docs, you can run `tools/bin/deploy_docusaurus` locally - this is the publish script that CI runs.
+The source code for the docs lives in the
+[airbyte monorepo's `docs/` directory](https://github.com/airbytehq/airbyte/tree/master/docs). Any
+changes to the `/docs` directory will be tested automatically in your PR. Be sure that you wait for
+the tests to pass before merging! If there are CI problems publishing your docs, you can run
+`tools/bin/deploy_docusaurus` locally - this is the publish script that CI runs.