owned this note   changed 2 years ago  
Published Linked with GitHub

Airbyte Connector Documentation Template

Hello 👋🏽

Thank you for your interest in contributing to Airbyte! Make a copy of the markdown template (sign-in to copy markdown version) and follow the writing guidelines to write Airbyte connector docs.

Writing guidelines

Our goal is to write user-centric docs that follow the 5 C's of effective communication:

  • Correct: Provide accurate, error-free information. Incorrect information can cost us credibility and user trust. To make sure the information is technically correct, test the instructions yourself and ask for engineering/PM reviews. To make sure the information is grammatically accurate, use tools like Grammarly.
  • Clear: Make sure the content is clear and comprehensible. Use technical jargon only if necessary. Define terms and acronyms that are new to the users or used differently from what they know. Include examples when applicable. Make sure the user can follow the instructions with minimal effort and not get lost in rambling sentences.
  • Concise: Make every word count. Remove any filler words. Use the imperative mood to write short, direct sentences.
  • Complete: Make sure the instructions are complete and cover all information that the users need for the task.
  • Consistent: Use terms and product names consistently (example: Google Cloud Storage bucket and not GCS bucket). Follow Google's text formatting guidelines.

The following highlights from the Google developer documentation style guide are helpful for new writers:

Guideline for visuals: Use links to videos instead of screenshots (Reason: Users are more forgiving of outdated videos than screenshots).

Make a copy of the following template to write your connector doc. For examples of good connector docs, see the Salesforce source connector doc and Snowflake destination connector doc

Template

<Connector name>

This page contains the setup guide and reference information for the <connector name> <source/destination> connector.

Prerequisites

Connector-specific prerequisites required for Airbyte Cloud and OSS. If the prerequisites are different, please create sub-headers for each (eg. ### For Airbyte Cloud, ### For Airbyte OSS)

Please also specify the permission or access-level required for any account associated with this connector

Setup guide

(If applicable) Step 1: Set up <connector name>

​
​

Step by step guide for setting up the tool before you can use it in Airbyte (example: create a read-only user by using the following script, create an S3 bucket)
Feel free to include code snippets and links to videos
​

For Airbyte Cloud:

​

Airbyte Cloud-specific steps (if any)

For Airbyte Open Source:

Airbyte Cloud-specific steps (if any)

​

Step 2: Set up the <connector name> connector in Airbyte

​

For Airbyte Cloud:

​

  1. Log into your Airbyte Cloud account.
  2. Click <Sources/Destinations> and then click + New source/destination.
  3. On the Set up the <source/destination> page, select <connector name> from the <Source/Destination> type dropdown.
  4. Enter a name for the <connector name> connector.
  5. <Fill in the rest of the steps>

​

For Airbyte Open Source:

​

Steps for Open Source
​

  1. Navigate to the Airbyte Open Source dashboard.

​

Supported sync modes

​
The <connector name> <source/destination> connector supports the following sync modes:
​

List supported sync modes
​
​

Supported Streams

​

List the name of supported streams with a link to their API endpoint docs
​

<Connector-specific features>

List the connector-specific features (if any)
​

Performance considerations

Describe performance considerations (if any)
​

Data type map

Include the data type map (if applicable)

Troubleshooting

​

Include bullet points for common issues that users might run into. In most cases, these should be within the body of your doc. (if applicable)
​

Tutorials

​

Include links to tutorials (if applicable)

Now that you have set up the <connector name> <source/destination> connector, check out the following <connector name> tutorials:

Select a repo