Skip to content
This repository has been archived by the owner on Nov 13, 2023. It is now read-only.

Latest commit

 

History

History
126 lines (86 loc) · 5.58 KB

updating-documentation.md

File metadata and controls

126 lines (86 loc) · 5.58 KB
Raw

Updating Documentation

We welcome contributions to the Airbyte documentation!

Our docs are written in Markdown following the Google developer documentation style guide and the files are stored in our Github repository. The docs are published at docs.airbyte.com using Docusaurus and GitHub Pages.

Finding good first issues

The Docs team maintains a list of #good-first-issues for new contributors.

  • If you're new to technical writing, start with the smaller issues (fixing typos, broken links, spelling and grammar, and so on). You can edit the files directly on GitHub.
  • If you're an experienced technical writer or a developer interested in technical writing, comment on an issue that interests you to discuss it with the Docs team. Once we decide on the approach and the tasks involved, edit the files and open a Pull Request for the Docs team to review.

Contributing to Airbyte docs

Before contributing to Airbyte docs, read the Airbyte Community Code of Conduct

:::tip If you're new to GitHub and Markdown, complete the First Contributions tutorial and learn Markdown basics before contributing to Airbyte documentation. :::

You can contribute to Airbyte docs in two ways:

Editing directly on GitHub

To make minor changes (example: fixing typos) or edit a single file, you can edit the file directly on GitHub:

  1. Click Edit this page at the bottom of any published document on docs.airbyte.com. You'll be taken to the GitHub editor.
  2. Edit the file directly on GitHub and open a Pull Request.

Editing on your local machine

To make complex changes or edit multiple files, edit the files on your local machine:

  1. Fork the Airbyte repository.

  2. Clone the fork on your local machine:

    git clone git@github.com:{YOUR_USERNAME}/airbyte.git
cd airbyte

    Or

    git clone https://github.com/{YOUR_USERNAME}/airbyte.git
cd airbyte

    While cloning on Windows, you might encounter errors about long filenames. Refer to the instructions here to correct it.

  3. Test changes locally:

Run the following commands in your terminal:

cd docusaurus
yarn install
yarn build
yarn serve

Then navigate to http://localhost:3000/ to see your changes. You can stop the running server in OSX/Linux by pressing Ctrl-C in the terminal.

  1. Follow the GitHub workflow to edit the files and create a pull request.

    :::note Before we accept any contributions, you'll need to sign the Contributor License Agreement (CLA). By signing a CLA, we can ensure that the community is free and confident in its ability to use your contributions. You will be prompted to sign the CLA while opening a pull request. :::

  2. Assign airbytehq/docs as a Reviewer for your pull request.

Additional guidelines

  • If you're updating a connector doc, follow the Connector documentation template
  • If you're adding a new file, update the sidebars.js file
  • If you're adding a README to a code module, make sure the README has the following components:
    • A brief description of the module
    • Development pre-requisites (like which language or binaries are required for development)
    • How to install dependencies
    • How to build and run the code locally & via Docker
    • Any other information needed for local iteration

Advanced tasks

Adding a redirect

To add a redirect, open the docusaurus.config.js file and locate the following commented section:

//                        {
//                         from: '/some-lame-path',
//                         to: '/a-much-cooler-uri',
//                        },

Copy this section, replace the values, and test the changes locally by going to the path you created a redirect for and verify that the address changes to the new one.

:::note Your path *needs a leading slash / to work :::

Deploying and reverting the documentation site

:::note Only the Airbyte team and maintainers have permissions to deploy the documentation site. :::

You'll need a GitHub SSH key to deploy the documentation site using the deployment tool.

To deploy the documentation site, run:

cd airbyte
# or cd airbyte-cloud  
git checkout master
git pull
./tools/bin/deploy_docusaurus

To revert/rollback doc changes, run:

cd airbyte
git checkout <OLDER_BRANCH>
./tools/bin/deploy_docusaurus