Merge pull request #658 from segmentio/repo-sync

repo sync

Author: bot-docsteam

CONTRIBUTING.md

@@ -12,14 +12,24 @@ Before you begin:
 
 Not all pages have a 1-1 mapping with their location within the repository. This can make browsing and locating the file you're trying to reference a challenge. As you browse [segment.com/docs](https://segment.com/docs), you'll notice two links in the right sidebar, at the top of the page. Click **Edit this page** to open the page in the GitHub editor. Or, click **Request docs change** to create a new issue that references the page.
 
+This is the best path to update a single page, or make a small change to a single article.
+
 ## Want to go deeper? Fork the repository
 
 You can fork this repository and clone it to your local machine to make larger changes. Examples of larger changes include:
 - editing more than one file at a time
 - adding or updating images
 - updating navigation items
 
-In this scenario, you'll fork the repository, clone it locally, make your changes, and submit a pull request to have them reviewed and merged back into the site.
+In this scenario, you'll fork the repository, clone it locally, make your changes, and submit a pull request to have them reviewed and merged back into the site. For more information, see the [Dev Guide](devguide.md).
+
+## Have your changes reviewed
+
+When you update a page on the Segment Docs site, either by the "Edit this page" link, or by forking the repository, your changes will go through the Pull Request process. When you open a Pull Request, you're saying "Hey Segment Docs team, I'd like to update the site with these updates." When the Pull Request is opened, it is assigned for review to the docs writer who is most active in that area of the documentation. This is maintained in the CODEOWNERS file. If there is no writer assigned to a specific area, your pull request will be randomly assigned to a member of the team.
+
+Once you submit, the reviewer may have questions about your submission. This conversation will take place with GitHub conversations in the context of the Pull Request.
+
+When your Pull Request is approved and merged, it will go live on the site with the teams next deploy (mornings, Pacific time on Tuesdays and Thursdays).
 
 ## Site structure
 
@@ -33,17 +43,17 @@ Anything that starts with an `_` is a utility directory of some sort (and Jekyll
 
 The most interesting ones are:
 - `/src/_includes/content/` This is where all the includes or "partials" - the reusable content - are stored.
-- `/src/_data/catalog/` This is where we keep the data we've pulled from the ConfigAPI in structured `yml` files that are used by the build.
-- `/src/_data/sidenav/` This is where the navigation structures are. (Several sections in the doc have their own left-nav, making them "microsites".) They're just YML files that we manually update so we have maximum control over what's shown and what's not.
+- `/src/_data/catalog/` This is where data pulled from the Public API is stored, in structured `yml` files that are used by the build.
+- `/src/_data/sidenav/` This is where the navigation structures are. (Several sections in the doc have their own left-nav, making them "microsites".) They're just YML files that manually updated.
 
 
 ### Images
 
-**Save all images locally! No linking to third-party hosted images!** Images are published to our CDN from the build step, and this means they won't go missing if the hosting service dujour goes out of business.
+**Save all images locally! No linking to third-party hosted images!** Images are published to the Netlify CDN from the build step.
 
-There are no _enforced_ naming conventions at this time. Files that start with an underscore are ignored by Jekyll. Anything you see with `asset` was dowloaded by a script to migrate it out of Contents.io.
+There are no _enforced_ naming conventions. Files that start with an underscore are ignored by Jekyll.
 
-In general, it's a good practice to name images with a description that helps you (& other docs maintainers) figure out where they should go within a page, or within a larger folder of images.
+It's a good practice to name images with a description that helps you (& other docs maintainers) figure out where they should go within a page, or within a larger folder of images.
 
 A few possibilities/suggestions:
 
@@ -63,9 +73,9 @@ Each also contains a `catalog` directory, which contains all the directories wit
 
 ### Programmatic content
 
-Programmatic content is sections of documentation that are built conditionally, or using public information from our Config API. This is *awesome* and like the holy grail of docs systems.
+Programmatic content is sections of documentation that are built conditionally, or using public information from the Public API.
 
-Programmatic content is built using information in the files in `/src/_data/catalog/`. These files (with the exception of `warehouses.yml`) are built by the `make catalog` command, which contacts our public ConfigAPI, gets a list of all the available integrations using the Catalog API, and then parses them into static `.yml` files.
+Programmatic content is built using information in the files in `/src/_data/catalog/`. These files (with the exception of `warehouses.yml`) are built by the `make catalog` command, which contacts the public Public API, gets a list of all the available integrations using the Catalog endpoint, and then parses them into static `.yml` files.
 
 Most of the programmatic content is built into the `_layouts` templates that each page uses. Sources, Destinations, and Warehouses use the `integration.html` template, which uses some Liquid logic, and calls an `include` depending on the integration type. Most of logic for the actual content must live in the include file itself, however logic controlling *if* the include is built can live in the `layout`.
 
@@ -94,7 +104,6 @@ Front matter variables have unique functions, including the following:
 
 #### Content-related front matter
 - `beta`: default false. When true, show an "in beta" warning in the page layout (see the warning in `_includes/content/beta-note.md`)
-- `rewrite`: defaults to false. This is a legacy front matter flag that comes from the old `site-docs` repo, and which labels any destination that was rewritten in ~2018 to a standardized template. It disables the duplicate "connection modes" table that would otherwise show up in the boilerplate content at the end of the page.
 - `hide-dossier`: defaults to false. When true, hides the "quick info" box at the top of a destination page.
 - `hide-boilerplate`: defaults to false. When true, none of the content from `destination-footer.md` is appended to the destination page.
 - `hide-cmodes`: defaults to false. A renaming of "rewrite" for more clarity, hides the connection modes table in the boilerplate.
@@ -103,12 +112,12 @@ Front matter variables have unique functions, including the following:
 - `source-type`: These are only used to supplement when a Cloud App in the sources path doesn't appear in the Config API list, and needs its type explicitly set. It runs some logic in the `cloud-app-note.md` to explain which cloud-apps are object vs event sources.
 
 #### Utility front matter
-- `published`: defaults to true. Set this to "false" to prevent Jekyll from rendering an HTML page for this file. Good for when you're working on something in the repo but aren't ready to release it yet, and don't want to use a Draft PR.
+- `published`: defaults to true. Set this to "false" to prevent Jekyll from rendering an HTML page for this file. Good for when you're working on something in the repository but aren't ready to release it yet, and don't want to use a Draft PR.
 - `hidden`: omits the file from the `sitemap.xml`, adds a `<meta name="robots" content="noindex" />` to the top of the generated HTML file, and drops it from the convenience script for regenerating the nav.
-- `hide-sidebar`: defaults to false. When true, hide the entire right-nav sidebar. Use with `hide-feedback` if you want to disable *all* feedback affordances.
-- `hide-feedback`: defaults to false. When true, hide the feedback in both rnav and footer. Good for landing pages.
+- `hide-sidebar`: defaults to false. When true, hide the entire right-nav sidebar. Use with `hide-feedback` if you want to disable *all* feedback opportunities.
+- `hide-feedback`: defaults to false. When true, hide the feedback in both nav and footer. Good for landing pages.
 - `hide_toc`: hides the right-nav TOC that's generated from H2s. Also good for landing pages.
 - `landing`: defaults to false. Use this to drop the noun set by `integration_type` from the tab title.
-- `redirect_from`: Defaults to null. Takes an array of URLs from the front matter in a file, and generates a "stub" page at each URL at build-time. Each stub file redirects to the original file. Use the path from the root of the content directory, for example `/connections/destinations/catalog/` rather than `/docs/connections/destinations/catalog/`. **Note** We are mostly using NGINX redirects for SEO purposes. Approximately quarterly, we'll collect these and add them to NGINX.
+- `redirect_from`: Defaults to null. Takes an array of URLs from the front matter in a file, and generates a "stub" page at each URL at build-time. Each stub file redirects to the original file. Use the path from the root of the content directory, for example `/connections/destinations/catalog/` rather than `/docs/connections/destinations/catalog/`.
 - `seo-changefreq`: default: `weekly `. Use the values [in the sitemap spec](https://www.sitemaps.org/protocol.html#xmlTagDefinitions). - sets the `changefreq` tag in the sitemap.xml generator, which tells search crawlers how often to check back.
 - `seo-priority`: values from `1.0` to `0.1`, default: `0.5 `. Sets the `Priority` tag in the sitemap

styleguide.md

@@ -8,22 +8,22 @@ This doc is for keeping track of [style decisions](#style-decisions), [structure
 
 - Titles and headings should be in sentence case, meaning you only capitalize the first word, and any product names and proper nouns.
 
-- UI items are described by their text label in **Bold**. We don't add an explicit reference to what type of affordance it is (button, toggle, etc) unless needed for clarity.  "Click **Send**." rather than "Click the **Send**  button."
+- UI items are described by their text label in **Bold**. Don't add an explicit reference to the type of control (button, toggle, etc) unless needed for clarity.  "Click **Send**." rather than "Click the **Send**  button."
 
 - Use single-backtick `code format` for variables, for commands or values that need to be entered by the user, and the names of methods or calls when referring to them in context of an implementation (for example: "You'll make an identify call to capture this information" vs "In your code, edit the `identify` call...").
 
 - One-line or less of code can be formatted using single-backtick "code format". For more than one line of code, use a code block.
 
 - Code blocks must use the triple-backtick format, and must include a syntax highlighter cue (even if that cue is "text" or "none".)
 
-### Use Active Voice / Write in the Present / Yes We Do
+### Use Active Voice / Write in the Present
 
 Write in the active voice.
 This one is harder to encapsulate.
 
 Instead of saying "Segment will create..." use "Segment creates..."
 Instead of saying "You should see your data in (x) minutes..." use "Your data arrives within..."
-Instead of saying "You will see a new dialog with your key..." use "A diaglog appears and displays your key..."
+Instead of saying "You will see a new dialog with your key..." use "A dialog appears and displays your key..."
 
 ### We and they
 
@@ -139,7 +139,7 @@ We have some fairly complex CSS, and lists with lots of "stuff" in them. Normall
 
 On top of this, some of the Premonition callouts we use, for some reason, break list ordering. So you can't add an "info" box inside a running list. (Boooo.)
 
-To get around this, you can let the previous list item end whereever if needs to, then create an entire new ordered list with specific HTML to allow you to override the start number.
+To get around this, you can let the previous list item end where ever if needs to, then create an entire new ordered list with specific HTML to allow you to override the start number.
 
 ```html
 <ol style="counter-reset: none;">
@@ -179,19 +179,6 @@ Tables in HTML can include html formatting, OR markdown formatting, but not both
 
 Many of these docs were exported from Paper, which means that they'll have some quirks to sort out.
 
-### Endumben-ing
-Paper uses smart-quotes and smart apostrophes, which often can break syntax-sensitive formatting. You can replace them with "dumb" or straight quotes. The characters you're going to want to look for are...
-
-’ ‘ “ ”  If you "change all" in Atom, you'll remove these examples so please revert changes to this file. ;)
-
-Note that these won't always render in Github, so you'll have to make this change using Atom or another text editor.
-
-If the examples get removed you can also type these on a Mac by typing
-- Option + [
-- Option + Shift + [
-- Option + ]
-- Option + Shift + ]
-
 ### Headings vs Titles
 
 Our titles are our H1s, so you can remove a top-line H1 if if shows up, and demote all following ones. (This assumes you're using heading formats semantically and not just for formatting. :P )
@@ -213,3 +200,7 @@ By default, Paper uses an old style of markdown that allows you to start a code
 Instead, de-indent your code (shift-tab), and add a code-fence of three backticks at the top and bottom.
 
 If you know what language it's in, you can also add a "cue" to the first codeblock, which improves how the syntax highlighter renders it (assuming it knows how to format that specific language). See the [section on code fences](#code-fences-and-syntax-highligher-cues) above for more details.
+
+### Linting
+
+Segment docs uses the Vale linter to enforce loose grammar guidelines. These checks run on any updated content as part of the Pull Request process, and can also be run locally if you install Vale. For more information, see [Vale.sh](https://www.vale.sh) or our implementation at `.github/styles`.