segmentio · markzegarelli · Nov 8, 2022 · Nov 7, 2022 · Nov 8, 2022 · Nov 8, 2022
@@ -102,7 +102,6 @@ NSDate
 NSNull
 NSNumber
 NSString
-OAuth
 Okta
 Omnichannel
 onboarding

@@ -12,24 +12,14 @@ 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. 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).
+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.
 
 ## Site structure
 
@@ -43,17 +33,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 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.
+- `/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.
 
 
 ### Images
 
-**Save all images locally! No linking to third-party hosted images!** Images are published to the Netlify CDN from the build step.
+**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.
 
-There are no _enforced_ naming conventions. Files that start with an underscore are ignored by Jekyll.
+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.
 
-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.
+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.
 
 A few possibilities/suggestions:
 
@@ -73,9 +63,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 the Public API.
+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 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.
+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.
 
 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`.
 
@@ -104,6 +94,7 @@ 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.
@@ -112,12 +103,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 repository 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 repo 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 opportunities.
-- `hide-feedback`: defaults to false. When true, hide the feedback in both nav 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 affordances.
+- `hide-feedback`: defaults to false. When true, hide the feedback in both rnav 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/`.
+- `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.
 - `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