diff --git a/README.md b/README.md index fcabf81..504a178 100644 --- a/README.md +++ b/README.md @@ -49,11 +49,17 @@ Once we get customers using your connector or destination, they can reach out to Our response times are articulated in our [Fivetran Support Policy](https://support.fivetran.com/hc/en-us/articles/5893119459223-Fivetran-Support-Policy) documentation. Bear in mind customers may expect your support response times to be similar. We recommend linking to your own SLAs/Support policies from the documentation you create for Fivetran. ### How do we create product documentation? -All Fivetran connectors have public documentation. For the SDK, we will need you to produce the following: +All Fivetran connectors have public documentation. For partner-built connectors, we will need you to produce the following: * Setup Guide [example](https://fivetran.com/docs/databases/cosmos/setup-guide) * Overview Page [example](https://fivetran.com/docs/databases/cosmos) -We’ll consume these docs and our tech-writing team will edit for grammar and style, sending back to your team (TBD on automation) to keep in sync. +To help you produce the documentation, we provide helpful resources: +* [Source connector templates](source-connector-templates/) +* [Destination connector templates](destination-connector-templates/) +* [Fivetran's documentation style guide](https://github.com/fivetran/fivetran_sdk/tree/main/style-guide/style-guide.md) +* [Fivetran-approved glossary of common terms](https://github.com/fivetran/fivetran_sdk/tree/main/style-guide/common-terms-glossary.md) + +We’ll review these docs and our Tech Writing team will edit for grammar and style, sending back to your team (TBD on automation) to keep in sync. The documentation is to be hosted in [Fivetran's documentation site](https://fivetran.com/docs/getting-started). ### How do we go-to-market? Fivetran will market through multiple methods: diff --git a/doc-templates/destination-connector-templates/destination-overview-template.md b/doc-templates/destination-connector-templates/destination-overview-template.md new file mode 100644 index 0000000..1985e7d --- /dev/null +++ b/doc-templates/destination-connector-templates/destination-overview-template.md @@ -0,0 +1,79 @@ +{This is a template for standard destination connector docs. Items between curly brackets need to be replaced with specific names or directions. For links to Fivetran documentation pages/sections, do _not_ use the absolute path format like [page name](https://fivetran.com/docs/...), use [page/section name](/docs/...) instead. Also, do _not_ include `/index.md` in the path, trim the path at the page directory. For example, [connector page name](/docs/connectors/applications/some-connector) is correct while [connector page name](/docs/connectors/applications/some-connector/index.md) is _incorrect_.} + +--- +name: {Item name in the left nav menu} +title: {SEO title} +description: {Meta Description} +hidden: {true or false. Set to true if the article should only be accessible via a direct link and not indexed by crawlers.} +--- + +# {Destination Name} + +{Description - Required - What is the service? Overview of what the service is (for example, Snowflake/Redshift). You can refer to publicly available documentation, however, remember to tailor it to Fivetran's context. Also, add a link to the related public website for the user’s reference.} + +{Example: [Azure Data Lake Storage](https://azure.microsoft.com/en-gb/products/storage/data-lake-storage/) is a cloud-based, scalable data storage solution for big data analytics. ADLS allows you to store and manage massive amounts of data in any format. Fivetran supports data lakes built on ADLS as a destination.} + +{Add this text to partner-built destination files: This destination is [partner-built](/docs/partner-built-program). For any questions related to {destination name} destination and its documentation, contact [{destination name} Support](_add support link_).} + +------------------ + +## Setup guide + +Follow our [step-by-step {Destination} setup guide](/docs/{path}/setup-guide) to connect your {Destination} destination with Fivetran. + +------------------ + +## Type transformation and mapping + +The data types in your {New Destination} follow Fivetran's [standard data type storage](/docs/destinations#datatypes). + +We use the following data type conversions: + +| Fivetran Data Type | Destination Data Type | Notes | +| - | - | - | +| BOOLEAN | BOOLEAN | | +| SHORT | SMALLINT | | +| INT | INTEGER | | +| LONG | BIGINT | | +| FLOAT | REAL | | +| DOUBLE | DOUBLEPRECISION | | +| BIGDECIMAL | DECIMAL | | +| LOCALDATE | DATE | | +| INSTANT | TIMESTAMP_TZ | | +| LOCALDATETIME | TIMESTAMP_NTZ | | +| STRING | VARCHAR or TEXT | VARCHAR if `bytelength`is present, else TEXT | +| JSON | VARIANT | | +| BINARY | BINARY | | + + + +> NOTE: SMALLINT, INTEGER, and BIGINT are synonymous with [NUMBER](https://docs.snowflake.com/en/sql-reference/data-types-numeric.html#int-integer-bigint-smallint-tinyint-byteint). + +------------------ + +## Hybrid Deployment support + +We {support/do not support} for the [Hybrid Deployment model](/docs/core-concepts/architecture/hybrid-deployment) for {destination name} destinations. + +------------------ + +## Limitations (if applicable) + +{Document the destination's limitations - for example, this destination does not support history mode.} + +------------------ + +## Optimize {Destination} (if applicable) +{List steps to optimize destination performance.} + +------------------ + +## Data load costs + +List any additional cost info our customers need to know. +------------------ + +## Migrate destinations {This is an example section} + +1. Enumerate the steps. +2. Use screenshots if necessary. \ No newline at end of file diff --git a/doc-templates/destination-connector-templates/destination-setup-guide-template.md b/doc-templates/destination-connector-templates/destination-setup-guide-template.md new file mode 100644 index 0000000..d6d884c --- /dev/null +++ b/doc-templates/destination-connector-templates/destination-setup-guide-template.md @@ -0,0 +1,86 @@ +{This is a destination connector setup guide template. Items between curly brackets need to be replaced with specific names or directions. For links to Fivetran documentation pages/sections, do _not_ use the absolute path format like [page name](https://fivetran.com/docs/...), use [page/section name](/docs/...) instead. Also, do _not_ include `/index.md` in the path, trim the path at the page directory. For example, [connector page name](/docs/connectors/applications/some-connector) is correct, while [connector page name](/docs/connectors/applications/some-connector/index.md) is _incorrect_.} + +--- +name: {Item name in the left nav menu} +title: {SEO title} +description: {Meta Description} +hidden: {true or false. Set to true if the article should only be accessible via a direct link and not indexed by crawlers.} +--- + +# {Destination Name} Setup Guide + +Follow our setup guide to connect {Destination} to Fivetran. + +----- + +## Prerequisites + +To connect a {Destination} to Fivetran, you need the following: + +{List what the user needs to know or do before they get started} + +- A Fivetran role with the [Create Destinations or Manage Destinations](/docs/using-fivetran/fivetran-dashboard/account-settings/role-based-access-control#rbacpermissions) permissions +- Administrator account {this is an example} +- Version 17 of Acme installed {this is an example} + +--- + +## Setup instructions + +### {Descriptive name of the step; for example, Get your API key} + +1. Enumerate the steps. +2. List one action per step. + {use screenshots when needed} + +### Second step + +1. Enumerate the steps. +2. List one action per step. + {use screenshots when needed} + +### Complete Fivetran configuration + +{Required} +1. Log in to your [Fivetran account](https://fivetran.com/login). +2. Go to the **Destinations** page and click **Add destination**. +3. Enter a **Destination name** of your choice and then click **Add**. +4. Select **** as the destination type. +5. In the destination setup form, enter the **Host** name you found in [Step 1](/docs/destinations/). +6. Enumerate the steps in from the destination setup form. +7. List one action per step. +8. Click **Save & Test**. + + Fivetran [tests and validates](/docs/destinations/newdestination/setup-guide#setuptests) the connection. Upon successfully completing the setup tests, you can sync your data using Fivetran connectors to the destination. + + +### Setup tests + +Fivetran performs the following {Destination} connection tests: : + +The Host Connection test checks the host's accessibility and validates the database credentials you provided in the setup form. +- The Validate Passphrase test validates your private key against the passphrase if you use key-pair authentication. +- The Default Warehouse test checks if the Snowflake warehouse exists and if you have set it as the default warehouse. +- The Database Connection test checks if we can connect to your Snowflake database. + The Permission test checks whether we have the CREATE SCHEMA and CREATE TEMPORARY TABLES permissions on your Snowflake database. + + > NOTE: The tests may take a couple of minutes to complete. + +--- + +## Related articles + +[ Destination Overview](/docs/destinations/newdestination) + + + +[ Release Notes](/docs/destinations/newdestination/changelog) + + + +[ API Destination Configuration](/docs/rest-api/destinations/config#newdestination) + + + +[ Documentation Home](/docs/getting-started) + diff --git a/doc-templates/source-connector-templates/connector-overview-template.md b/doc-templates/source-connector-templates/connector-overview-template.md new file mode 100644 index 0000000..b544cf4 --- /dev/null +++ b/doc-templates/source-connector-templates/connector-overview-template.md @@ -0,0 +1,62 @@ +{This is a template for the source connector overview page. Items between curly brackets need to be replaced with specific names or directions. For links to Fivetran documentation pages/sections, do _not_ use the absolute path format like [page name](https://fivetran.com/docs/...), use [page/section name](/docs/...) instead. Also, do _not_ include `/index.md` in the path, trim the path at the page directory. For example, [connector page name](/docs/connectors/applications/some-connector) is correct while [connector page name](/docs/connectors/applications/some-connector/index.md) is _incorrect_.} + +--- +name: {Item name in the left nav menu} +title: {Source system} connector by Fivetran | Fivetran documentation +Description: Connect your {source system} data to your destination using Fivetran. +hidden: {true or false. Set to true if the article should only be accessible via a direct link and not indexed by crawlers.} +--- + +# {Source Connector Name} {% typeBadge connector="connector_name" /%} {% availabilityBadge connector="connector_name" /%} + +{Description - Required - What is the service? Overview of what the service is (Marketo = Email marketing tool). You can refer to publicly available documentation, however, remember to tailor it to Fivetran's context. +Also, add a link to a related public website for users’ reference.} + +{Example: [15Five](https://www.15five.com/) is an employee performance management platform.} + +------------------ + +## Features + +{List the supported features and their notes separated by a colon to populate the Supported and Notes columns of the Feature table. Unsupported features are added automatically. Use the colon after the feature name. Each feature should be on a new line. The feature list should be wrapped by `{% featureTable connector="connector_id" %} ... {% /featureTable %}`. It helps to autopopulate some data in the Note column. If you want to add a new feature to the Feature table or change a link of an existing feature, make the relevant change to the template file: `/docs/_template_articles/feature-table.yaml`. Add notes to clarify the conditions under which the particular feature is supported for the connector. For example, if a connector only supports custom data for certain tables, specify these tables. Or, if a connector supports data blocking at every level, list all the levels: "Column level, table level, and schema level". For definitions of features, see our [Features documentation](https://fivetran.com/docs/using-fivetran/features). } + +{% featureTable connector="connector_id" %} +Capture Deletes: +Custom Data: +Data Blocking: +Column Hashing: +Re-sync: Connector level +History Mode: +API Configurable: +Priority-first sync: +Fivetran data models: +Private Networking: +{% /featureTable %} + +{ If the connector supports API configuration, add it to the list of [Connectors supported by API and their authorization methods] +(/docs/rest-api/getting-started#connectorssupportedbyapiandtheirauthorizationmethods) and specify whether it supports Connect Card and API authorization.} + +------------------ + +## Setup guide + +Follow our [step-by-step {Connector name} setup guide](/docs/{path}/setup-guide) to connect {Connector} with your destination using Fivetran connectors. + +------------------ + +## Sync overview + +{Optional} +{Brief overview of how the connector works. +What processes do we use to sync the data? Query the initial sync, then read off the logs? +If the connector uses webhooks as part of its sync strategy, add it to the list in the [Exceptions section](/docs/security#exceptions) - under the **Event data from the Webhooks connector and other connectors using webhooks** item. Also, specify its data retention period.} + +{Use subheadings (### and ####) to cover items such as rollback syncs and conversion windows} + +------------------ + +## Schema information + +{Embed a link to the connector’s ERD.} + +{In subheadings (### and ####) cover items such as initial sync, updating data, deleted rows, deleted columns, type transformations and mapping, and Fivetran-generated columns.} diff --git a/doc-templates/source-connector-templates/connector-setup-guide-template.md b/doc-templates/source-connector-templates/connector-setup-guide-template.md new file mode 100644 index 0000000..3be8ff7 --- /dev/null +++ b/doc-templates/source-connector-templates/connector-setup-guide-template.md @@ -0,0 +1,83 @@ +{This is a connector setup guide template. Items between curly brackets need to be replaced with specific names or directions. For links to Fivetran documentation pages/sections, do _not_ use the absolute path format like [page name](https://fivetran.com/docs/...), use [page/section name](/docs/...) instead. Also, do _not_ include `/index.md` in the path, trim the path at the page directory. For example, [connector page name](/docs/connectors/applications/some-connector) is correct while [connector page name](/docs/connectors/applications/some-connector/index.md) is _incorrect_.} + +--- +name: {Item name in the left nav menu} +title: {SEO title} +description: {Meta Description - Example: Read step-by-step instructions on how to connect {Source system} with your destination using Fivetran connectors.} +hidden: {true or false. Set to true if the article should only be accessible via a direct link and not indexed by crawlers.} +--- + +# {Connector} Setup Guide {% typeBadge connector="connector_name" /%} {% availabilityBadge connector="connector_name" /%} + +Follow our setup guide to connect {Connector} to Fivetran. + +----- + +## Prerequisites + +{Required} + +To connect your {Source Connector} account to Fivetran, you need: +{List what the user needs to know or do before they get started} + +- Administrator account {this is an example} +- Version 17 of Acme installed {this is an example} + +--- + +## Setup instructions + +To authorize Fivetran to connect to your {Connector} app, follow these instructions: + +### {Descriptive name of step, for example, Get your API key} + +1. Enumerate the steps. +2. List one action per step. + {use screenshots when needed} + +### Second step + +1. Enumerate the steps. +2. List one action per step. + {use screenshots when needed} + +### Finish Fivetran configuration + +{Required} +1. In the [connector setup form](/docs/using-fivetran/fivetran-dashboard/connectors#addanewconnector), enter {field specific to this connector}. +1. {Additional instructions for this specific connector} +1. Click **Save & Test**. Fivetran will take it from here and sync your data from your {Connector Name} account. + +### Setup tests (applies to all connectors but Applications connectors) + +{List the setup tests that we run in the Fivetran dashboard for this connector.} + +Fivetran performs the following {Connector} connection tests: +- The Validate Secrets test checks if you have entered the secrets in a valid JSON format. {this is an example} +- The Connecting to AWS test checks the connection and the cluster accessibility. {this is an example} + + +--- + +## Related articles + +[ Connector Overview](/docs/connectors/{connector category}/newconnector) +{Replace "connector category" with the actual category the connector falls into. The options are applications, databases, events, files, or functions.} + + + +[ Schema Information](/docs/connectors/{connector category}/newconnector#schemainformation) +{Replace "connector category" with the actual category the connector falls into. The options are applications, databases, events, files, or functions.} + + + +[ Release Notes](/docs/connectors/{connector category}/newconnector/changelog) +{Only add the Release Notes related article if the connector is in Beta or GA. Private Preview connectors don't have release notes.} + + + +[ API Connector Configuration](/docs/rest-api/connectors/config#newconnector) + + + +[ Documentation Home](/docs/getting-started) diff --git a/doc-templates/style-guide/common-terms-glossary.md b/doc-templates/style-guide/common-terms-glossary.md new file mode 100644 index 0000000..957cb80 --- /dev/null +++ b/doc-templates/style-guide/common-terms-glossary.md @@ -0,0 +1,384 @@ +# Glossary of Approved Terms + +Fivetran provides this glossary of approved terms as a resource for SDK connector partners. + +This glossary is not an extensive list of terms that may be used in the documentation. For any professional term that is not mentioned in this document, default to the industry standard. For general spelling and usage, follow [Merriam-Webster.com](https://www.merriam-webster.com/). The Merriam-Webster dictionary is the primary dictionary for the AP Style, which is the backbone of the Fivetran style. + +## Approved word list + +Use **lets** instead of **allows**; it’s shorter and saves a word. + +* RIGHT: lets you connect +* WRONG: allows you to connect + +**alternately** has multiple meanings; use **alternatively** instead. + +* RIGHT: You can do X. Alternatively, you can do Y. +* WRONG: You can do X. Alternately, you can do Y. + +**binary log**, *not* Binary Log + +Use **denylist**, not **blacklist**. + +**boolean** does not need to be capitalized + +**change data capture** and **change tracking** (SQL Server database's incremental update mechanisms) should not be capitalized + +**change history tracking (CHT)** for anything [change history tracking](https://fivetran.com/docs/using-fivetran/features#history)\-related + +**child table**, *not* sub-table. + +**checkbox**, *not* check box or tick box. When you describe how to interact with a checkbox, use **select**, *not* check, and **clear**, *not* un-check. + +**chosen**, *not* desired. While North American English often uses "desired" in a non-romantic context, some other English dialects do not (for example, British English in India). + +**drop-down menu**, *not* dropdown. + +**either** can be used for more than 2 items. **Example**: Table names will be in *either* the COMPLETE, IN\_PROGRESS, or NOT\_STARTED state, depending on their sync status. + +**false** Lowercase unless part of a code block, then uppercase or sentence case depending on the language (for SQL keywords and key pairs, always use uppercase). Format as code when written as text. For example, "set the column value to `false`." + +**Fivetran dashboard**, *no*t Fivetran Dashboard. Also, **Your Fivetran dashboard**, *not* The Fivetran dashboard. Also, **In your Fivetran dashboard**, *not* On your Fivetran dashboard. + +**full sync** \- don't use. Use **historical sync** instead. + +**integration** \- don't use. In the common context of connector, use **connector** instead. + +**log in** and **login**: + +* **Log in**: when it is an action. **Example**: *Log in* to your website. +* **Login**: When it is a thing or a modifier using an adjective. **Example**: Go to the *login* page. + +**log in to**, *not* log into + +**make a note of** a field, *not* copy or save. **Example**: Make a note of the API key. You will need it to configure Fivetran. + +**monthly active rows** spell out in lower case the first time it's used on a page. Follow with the acronym if it will be used multiple times. **Example:** In this document, you will learn how *monthly active rows (MAR)* are calculated, how to track your *MAR*, and how to optimize your usage. + +**More Options menu**, *not* three vertical dots or right menu + +**master** (as in master database) don't use. Use **primary** instead. + +**navigation menu**, *not* sidebar + +**null** Lowercase unless part of a code block, then uppercase or sentence case depending on the language (for SQL keywords and key pairs, always use uppercase). Format as code when written as text. For example, "the column displays a `null` value." + +**pop-up**, *not* popover + +**PostgreSQL**, *not* Postgres + +**re-sync**, not resync + +**set up** and **setup.** + +* **Set up**: when it is an action. **Example**: *Set up* your account. +* **Setup**: When it is a thing. **Example**: Go to the *setup* form. + +**slave** (as in slave database) don't use. Use **replica** instead. + +**SQL** Use with “a,” not “an.” While there is some debate as to whether it should be pronounced “sequel” or “ess-que-el,” “sequel” is the more common pronunciation and is the one we use internally. + +* RIGHT: A SQL database +* WRONG: An SQL database + +**sync** use in the sense of “syncing a connector”; avoid using in other ways to preserve that meaning; *do not* use **update** in its place + +**task** Capitalize when it refers to a Task alert generated in the Fivetran dashboard. For example, "Resolve the Task on the Alerts page." + +**time zone**, *not* timezone + +**true** Lowercase unless part of a code block, then uppercase or sentence case depending on the language (for SQL keywords and key pairs, always use uppercase). Format as code when written as text. For example, "set the column value to `true`." + +**via** Don’t use it. Use the appropriate English word instead (for example, “by” or “through"). Via is vague and thus potentially confusing. + +**warning** Capitalize when it refers to a Warning alert generated in the Fivetran dashboard. For example, "Dismiss the Warning on the Alerts page." + +**whitelist** Don't use. Use **safelist** instead. See also [Writing inclusive documentation](https://developers.google.com/style/inclusive-documentation). + +**user** *not* customer + +**update** *do not* use to mean sync a connector + +**URL**, *not* URL path or path + +**comma-separated**, not comma separated. + +## Approved spelling + +Here’s a list of words we often use at Fivetran whose spelling and/or punctuation can be confusing. Do it this way\! + +**ad hoc:** do not hyphenate as modifier: *ad hoc solution* + +**add-on**: hyphenate when using to describe browser extensions, pieces of supplemental infrastructure, etc. + +**admin**: acceptable as abbrev. + +**airtight**: no hyphen + +**analytics:** use as both noun and adjective (e.g., *marketing analytics*, *analytics solutions*, etc. — not *analytic solutions*) + +**autogenerate**: no hyphen + +**autopopulate**: no hyphen + +**B-tree**: capital *B*; this is current common usage + +**backend**: one word + +**Bay Area**: capitalize (proper name) + +**beta**: do not capitalize: *Fivetran has released the Pendo connector in beta* + +**big data**: lowercase + +**built-in**: hyphenate when using as a modifier (*built-in dashboard* vs. *the dashboard was built in*) + +**business intelligence**: lowercase + +**change data capture:** lowercase + +**cheat sheet:** two words + +**cloud**: lowercase unless part of a product name + +**cloud functions:** lowercase unless part of a product name (*Google Cloud Functions*) + +**co-founder:** lowercase descriptive, not formal title; use hyphen + +**column blocking**: no hyphen as noun + +**column hashing**: no hyphen as noun + +**communications**: generally, use the plural when referring to a system, e.g.: *communications technology*, *satellite communications* + +**cost-effectiveness/cost-effective**: hyphenate + +**credit consumption**: \*\*\*\* lowercase + +**cyberthreat**: one word + +**cyberattack**: one word + +**dashboard**: one word + +**data**: treat as singular noun: *ensure your data is updated in real time*, not *ensure your data are updated in real time* + +**database management system**: lowercase; can use DBMS + +**data center**: two words, lowercase + +**data lake**: two words, lowercase + +**data pipeline**: two words, lowercase + +**data set**: two words (not *dataset*) + +**data sheet**: \*\*\*\* two words + +**data stack**: two words + +**datastore**: one word + +**data warehouse:** lowercase + +**decision-making**: use hyphen + +**deduplicate**: no hyphen + +**demo:** lowercase (common noun) + +**denormalize**: no hyphen + +**double-click**: hyphenate as both noun and verb + +**downtime**: one word + +**ebook**: no hyphen, not *eBook*; capitalize as *Ebook* + +**ecommerce**: no hyphen, not *eCommerce*; capitalize as *Ecommerce* + +**email**: no hyphen + +**end-to-end**: hyphenate when using as modifier (*end-to-end encryption*) + +**end user**: two words + +**endpoint**: one word + +**entity-relationship diagram**: lowercase (not a proper noun) with hyphen; acronym is *ERD* + +**EU:** no periods for *European Union* acronym + +**everyday**: one word as adj. (*everyday task*); two words as adv. (*it happened every day*) + +**eventual consistency:** lowercase (not a proper noun), and do not hyphenate adj. form: *eventually consistent service* + +**filename**: one word + +**firsthand:** one word + +**five-minute**: not 5-minute + +**fivetran.com vs.** [**https://www.fivetran.com**](https://www.fivetran.com): use *fivetran.com*; the https prefix is no longer needed + +**fully managed**: no hyphen in this adv. phrase + +**generative AI:** lower case "g". Appreviated as "GenAI" with a capital "G". + +**geolocation**: no hyphen + +**geotagging**: no hyphen + +**handoff/hand off**: *handoff* as noun, *hand off* as verb + +**hash map:** two words + +**hash table:** two words + +**healthcare**: one word + +**help desk**: two words + +**high-volume replication:** lowercase, hyphenate *high-volume* + +**homepage**: one word + +**ID**: all caps, as in *field ID*, *user ID,* or *ID card* (not *id* or *Id*) + +**internet**: lowercase + +**JOIN:** all-caps when referring to the SQL keyword, and when possible in a monotype font to indicate code style + +**jump-start**: use hyphen for both noun and verb + +**kickoff/kick off:** one word as noun, two words as verb + +**know-how**: hyphenate as noun + +**log-based replication**: use hyphen + +**login/log in**: *login* as a noun, *log in* as a verb + +**long-term**: hyphenate when using as modifier (*long-term risk* vs. *over the long term*) + +**low-impact:** hyphenate when using as modifier (*low-impact data replication*) + +**metadata**: one word, no hyphen + +**modern data stack:** lowercase (not proprietary, not a formal product, not a proper noun) + +**monthly active rows**: lowercase + +**multifactor**: no hyphen + +**non**\-: generally, use this prefix without a hyphen: *nonprofit*, *nonzero*, *noncompliance*, *nondenominational*; hyphenate before proper nouns (*non-Euclidean geometry*) + +**off-the-shelf**: hyphenate when using as modifier: *off-the-shelf solution*; do not hyphenate when using as a prepositional phrase: *she bought it off the shelf* + +**on-demand/on demand:** hyphenate as modifier preceding noun: *on-demand webinar*; no hyphen when used as prepositional phrase: *data available on demand* + +**online**: one word + +**onshore:** one word, not *on-shore* + +**on-site**: not *onsite* + +**on-premises**: (not *on-premise or on-prem*) + +**open source/open-source**: hyphenate when using as modifier (*open-source system*) + +**payoff:** one word + +**Ph.D.**: use two periods, not *PhD* + +**pinpoint:** no hyphen + +**prebuilt**: no hyphen + +**predefined**: no hyphen + +**predetermined**: no hyphen + +**pre-engineered**: use hyphen (vowel repetition) + +**preprocessing**: no hyphen + +**ready-to-query**: hyphenate when using as a modifier (*ready-to-query data* vs. *data that arrives ready to query*) + +**real-time/real time**: hyphenate when using as modifier (*real-time data delivery* vs. *updates in real time*) + +**re-import**: hyphen + +**rename**: no hyphen + +**resync**: no hyphen + +**retry**: no hyphen + +**rollout vs. roll out**: \*\*\*\* one word as noun (*rollout*), two words as verb (*roll out*); no hyphen in either case + +**screenshot**: one word + +**setup/set up**: *setup* as noun, *set up* as verb + +**shareable:** not *sharable* + +**shoestring**: one word, no hyphen + +**secure sign-on:** lowercase, hyphenate *sign-on*; use two hyphens in adj. form: *secure-sign-on service* + +**single sign-on**: lowercase, one hyphen, but use two hyphens in adj. form: *single-sign-on service* + +**skill set**: two words, not *skillset* + +**stand-alone**: hyphenate + +**startup**: one word + +**sub-table**: hyphenate for clarity + +**systems integrator/systems integration**: use the plural *systems*, not singular *system*; hyphenate when using as modifier: *systems-integration engineer* + +**third party/third-party**: hyphenate when using as modifier (*third-party app*) + +**time frame**: two words, not *timeframe* + +**timeout/time out**: *timeout* as noun, *time out* as verb + +**timestamp**: one word, per coding convention (NB: this deviates from AP style) + +**tool set**: two words (not *toolset*) + +**touchpoint**: one word + +**trend analysis**: two words, no hyphen unless using as a modifier (*trend-analysis team*) + +**trendline**: one word, not *trend line* + +**troubleshoot**: one word, no hyphen + +**turnkey**: one word + +**U.K.**: use periods in *United Kingdom* acronym + +**underscore**: one word as both verb and noun + +**up to date/up-to-date:** hyphenate when used as modifier (*up-to-date data* vs. *the data is up to date*) + +**U.S.**: use periods in *United States* acronym + +**username**: one word + +**vs.:** always use a period + +**watertight**: no hyphen + +**web**: lowercase + +**webhook**: lowercase (not a proper noun) + +**website**: one word, not *web site* or *web-site* + +**white paper**: two words + +**yearlong:** one word \ No newline at end of file diff --git a/doc-templates/style-guide/style-guide.md b/doc-templates/style-guide/style-guide.md new file mode 100644 index 0000000..a198927 --- /dev/null +++ b/doc-templates/style-guide/style-guide.md @@ -0,0 +1,266 @@ +# Documentation Style Guide for Connector SDK Partners + +Use this style guide to help you write effective documentation for Fivetran SDK connectors. + +For technical language and formatting not specified here, follow the [Google developer documentation style guide](https://developers.google.com/style). + +For general spelling and usage, follow [Merriam-Webster.com](https://www.merriam-webster.com/). For other style questions not covered here, follow AP Style. + +## Voice + +Fivetran advocates for simple, friendly technical communication that’s easily understood by international audiences. Adhere to the following best practices: + +* Use plain language/plain English practices**.** +* Use simple international English. +* Use simple words. +* Prefer short sentences. +* Prefer the use of active voice. +* Use the present tense. +* Use U.S. date format (month/day/year). + +**Talk to the users, not about them.** + +**You**, not the user. + +* RIGHT: You can select which tables to sync. +* WRONG: The user can select which tables to sync. + +### What doesn’t belong in the documentation? + +* Don’t use language that points to a specific point in time (e.g., now, new, yet, currently, in the future, soon, etc.) Refer to [Google’s guide to writing timeless documentation](https://developers.google.com/style/timeless-documentation). +* Don’t make vague promises about the future in the documentation. The documentation represents the present reality. +* Don’t add information or language you wouldn’t expect in technical documentation (e.g., persuasive language, marketing language, comparing with other products, etc.) +* Don’t put to-do notes about missing parts in the documentation. The documentation must be complete. +* Avoid plagiarism. Never copy-paste content from another source. Paraphrasing is OK, but even then, try to add more value to the content. + +## Procedural docs (step-by-step docs) + +Number the steps. Do not use indefinite or definite articles in step headings. For example, "Run `some_command` in your database cluster", "Create new user in Fivetran". + +Write one action per step. + +* RIGHT: 1\. Select **Foo** in the navbar. 2\. Click **OK**. +* WRONG: 1\. Select **Foo** in the navbar, then click **OK**. + +When referring to a step, use the name of that step, *not* the number. For example, "the Finish Fivetran configuration" step (see [example](https://fivetran.com/docs/connectors/databases/planetscale/setup-guide#finishfivetranconfiguration)). + +## Screenshots + +* Use screenshots when a visual makes your point more clear. +* Don’t use screenshots for text-only elements. For example, if you write “Click OK,” you don’t need a screenshot of the OK button. +* Make a screenshot of the smallest possible area to show only the relevant information. +* Close any elements (modals, popups) that don't have the info you're trying to show. +* Minimize unnecessary empty space by resizing the browser window. +* Avoid both very wide and very long screenshots since they may not display well in the documentation. +* All screenshots in Fivetran documentation are .png images. + +## Links/URLs + +When linking to a documentation page (internal or external), use the page or section name in your anchor text to be more specific. That way, users still know what information to look for if the link breaks. + +* RIGHT: Learn more in [Facebook's Budgets documentation](https://developers.facebook.com/docs/marketing-api/bidding/overview/budgets/). +* WRONG: Learn more in [Facebook's documentation](https://developers.facebook.com/docs/marketing-api/bidding/overview/budgets/). +* WRONG: [Click here](https://developers.facebook.com/docs/marketing-api/bidding/overview/budgets/) to learn more. + +Use “see” or “learn more” to refer to links and cross-references. + +* RIGHT: For more information about data storage platforms that we support, see [our Destinations documentation](https://fivetran.com/docs/destinations). + +For further information and examples, see [Google’s Cross-References guide](https://developers.google.com/style/cross-references). + +### Placeholder values for examples and screenshots + +**Names:** Firstname Lastname + +**User Icon:** Default empty headshot + +**Passwords:** mypassword + +## Placeholder variables in code blocks + +Prefer descriptive names for what the variable does rather than examples or nonsense words. + +Format placeholder values in italics. For italics to work in Fivetran docs, you must set the language to shell: + +```` +```shell +GRANT USAGE ON SCHEMA "some_schema" TO username; +``` +```` + +## General language usage + +Adhere to the following general language guidelines: + +- Use American English spelling. +- Adhere to AP style unless specified otherwise. +- Use sentence case for titles and headings. +- Don’t use end punctuation in headers or subheaders. + +### Titles and headers + +Use title case for the page title and sentence case for all subsequent headers. In public-facing Fivetran docs, the title is H1, `#` in Markdown. + +* Use H1 for main titles, H2 for sections, and H3 for subsections to make content easier to read and crawl. +* Headings must go in order (H1 → H2 → H3 → H4). Don’t skip levels. +* Use only one H1 per page. +* Create unique and descriptive titles for each page. +* Top-level headings (H2) should communicate what's most important to the article. +* Don't overuse headings. If you are introducing a heading for just a single paragraph of content, consider whether the heading is really necessary. +* Keep headings short. Be specific and put the most important idea first. +* Avoid following a heading with another heading with no content in between. + +### Tense + +Use present tense, not future tense. **Fivetran loads your tables**, *not* Fivetran will load your tables. + +### Plagiarism + +Never copy-paste content from another source. Paraphrasing is fine, but even then, try to add more value to the content. + +### Table names vs. column names + +* Write table names in **ALL\_CAPS**. +* Write column/ field names in all **lower\_case**. + +### Code formatting + +Use code style for code examples, keywords, values, table names, and field/column names. For example, the boolean keywords/values `true` and `false`, the string/value `“foo”`, the integer `1234`, the keyword `print`, the table name `ALL_CAPS`, and the column name `lower_case` should all be code-styled. + +### Readable and scannable content + +Use bullet points, short paragraphs, and concise sentences to make content easily digestible. + +Use tables to make complex information more easily understood by presenting it in a clear structure. Make sure the purpose of the table is straightforward. Include a table title or brief introduction to set the tone if necessary. + +### Bold + +Use bold to indicate UI elements. For example: Click **Save & Test**. + +### Emphasis + +Use *italics* to emphasize a piece of information. Use italics sparingly. Never use all caps for emphasis. + +### Notes + +Use note style ( `>` in Markdown) for notes. Do not use the `{% info %}` note style. How you introduce your note depends on the urgency of its content: + +* WARNING: The most urgent note type. Tells users how to avoid critical errors, like breaking their connector or overloading their destination. For example: + +WARNING: MySQL databases can fail to perform basic queries for even medium volumes of data and is inappropriate for a data warehouse. + +* IMPORTANT: The second-most urgent note type. Tells users how to set up and use Fivetran successfully. For example: + +IMPORTANT: You must have TLS enabled on your database to connect to Fivetran directly. + +* NOTE: The second-least urgent note type. Provides additional context or explanations about the document's content. For example: + +NOTE: If you have a Standard or Enterprise account, you can also manage your Fivetran account and its connectors using our REST API. + +* TIP: The least urgent note type. Contains your recommendations and tips; users don't need this information, but it's nice for them to know. For example: + +TIP: Click **Show** to view your Secret Key. + +### Data types + +When listing data types, write their names in all caps, but *do not* put them in code style. For example, INTEGER, STRING, BINARY. + +### Oxford comma + +Use the [serial (Oxford) comma](https://www.grammarly.com/blog/what-is-the-oxford-comma-and-why-do-people-care-so-much-about-it/) in lists of three or more items. Serial commas make lists easier to read. They also prevent ambiguity. For example: + +I love my parents, Jane and John. + +Without the serial comma, you can interpret this sentence in two ways: + +1. I love my parents, Jane, and John. +2. I love my parents, and my parents are Jane and John. + +The serial comma, however, leaves no room for interpretation: + + I love my parents, Jane, and John. + +### Percent (%) + +Use the symbol (%) instead of spelling out percent. + +## Ampersand (&) + +Avoid using in-body text; use “and” instead. Also, avoid using headlines/headers and subheaders unless necessary for space or design. + +### Courtesies (do not use\!) + +When writing docs, instructions, and error messages, avoid *please*, *thank you*, and so on. Save your reader's time. + +* **Correct**: Click the button to update your account settings. +* **Incorrect**: We request that you please click the button to update your account settings. Thank you\! + +### Spell out an acronym in its first use + +Don’t assume the reader knows an acronym. When first mentioning an acronym, write the full term with the acronym in parentheses. + +### Numbers + +Spell out numbers one through nine, and use figures for 10 and above. + +Generally, use numerals with *million*, *billion*, *trillion*, etc.: + +* *They built 1 billion new units*. + +Not necessary with casual uses: + +* *She could think of a billion reasons to decline the offer.* + +When starting sentences, always spell out numbers: + +* *Thirty-four days and nine hours later, he reconsidered.* + +### Date/ time + +Generally, spell out months. Use standard date notation format. For example, January 1, 2020, *not* January 1st, 2020\. + +Use **a.m./p.m.** *not* **AM/PM**. + +### Parentheses + +Generally, use parentheses sparingly, as they pull the reader out of the flow of the sentence. Keep the information inside parentheses short, and consider em dashes or commas instead. If you’re trying to stuff a lot of information into parentheses, you should probably rewrite the sentence or break it in two. + +**Correct:** They were frustrated with ineffective data movement methods (including DIY) as they expanded. + +**Incorrect:** They were frustrated with ineffective data movement methods (including DIY and legacy platforms such as ABC and DEF that ate time and resources) as they expanded. + +### Bullets + +Use bullets when there is a list of three or more items. If the list contains one or two items, simply include it in a sentence. + +**Example**: + +We have added two new tables, \`PRODUCT\_DIMENSION\_PERFORMANCE\_REPORT\` and \`PRODUCT\_DIMENSION\_IMPRESSION\_PERFORMANCE\_REPORT\`. + +**not** + +We have added two new tables: + +* \`PRODUCT\_DIMENSION\_PERFORMANCE\_REPORT\` +* \`PRODUCT\_DIMENSION\_IMPRESSION\_PERFORMANCE\_REPORT\` + +### Postscripts + +Mark all relevant fields with an asterisk (`*`) to include a postscript. Add your postscript in note format and begin the note with an asterisk (`*NOTE:`). + +While asterisks are a special character in Markdown, you do *not* need to escape an asterisk in note format. If you need to use two asterisks in the same sentence, put a space before the second one to avoid italics ([the automatic Markdown formatting](https://www.markdownguide.org/basic-syntax/#italic)). See [example of a postscript](https://fivetran.com/docs/destinations/clickhouse#typetransformationmapping). + +## Release phases + +We release new features, connectors, and destinations in phases to ensure we provide our users with the highest-quality experience. Below, we have outlined the expected user experience for each phase. + +| PHASE | DEFINITION | +|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Private Preview | We release private preview versions of new features, connectors, or destinations to a small group of customers to verify functionality and address issues. Releases in the private preview phase are hidden from non-participating users. Private preview releases are likely to be missing some functionality, and known or unknown issues may surface. We cannot guarantee a quick resolution to these issues during the private preview phase. When a feature, connector, or destination is in Private Preview, its [Monthly Active Rows (MAR)](https://fivetran.com/docs/usage-based-pricing#monthlyactiverows) are free. | +| Beta | We use beta releases to test functionality with a broader audience. Beta releases are available to any customer who wishes to use them. In beta, the functionality is complete, and the goal is to test more edge cases. We address issues as soon as possible according to our Support SLA. | +| Generally Available | We release features or connectors as generally available once we have validated their quality and are sure we’ve identified all major technical issues in the previous two phases. If problems arise, we respond and address them as soon as possible according to our Support SLA. | +| Sunset | We sunset a feature, connector, or destination once we have identified a better solution that requires a breaking change. We notify users at least 90 days in advance of a sunset. | + +## Useful documentation tools + +Convert Google Docs to Markdown. Use Google Docs built-in functionality to [export a Google Doc as Markdown](https://support.google.com/docs/answer/12014036#zippy=%2Cexport-a-google-doc-as-markdown) or [copy Google Docs content as Markdown](https://support.google.com/docs/answer/12014036#zippy=%2Ccopy-google-docs-content-as-markdown). \ No newline at end of file