Merge branch 'master' into DOC-204_papi_catalog

Author: markzegarelli

.env.example

@@ -1 +1,2 @@
-PLATFORM_API_TOKEN=look for me in chamber
+PLATFORM_API_TOKEN=look for me in chamber
+PAPI_TOKEN=get one from a papi-enabled workspace

README.md

@@ -64,7 +64,7 @@ See the [Contributor Guide](contributors.md) for more info.
 
 If you're planning substantial changes to the docs, follow this process for great success! 🏆
 
-1. 📞 Contact the docs team* during the planning phase. This way, we can help with logistics and information architecture, and alert you to any gotchas in your content area.
+1. 📞 Contact the docs team ( @segmentio/segment-doc-team ) during the planning phase. This way, we can help with logistics and information architecture, and alert you to any gotchas in your content area.
 2. 📝 Unless previously booked, we don't need to be involved in the writing - go for it! (We're happy to consult if you get stuck or need someone to bounce ideas off.)
 3. 👀 When you've got a draft at least 70% ready for review, tag a member of the docs team, who'll do an initial review. (This can be either in Paper/Gdocs, or in a Github [Draft PR](#draft-prs) with markdown changes if you're comfortable with that.) They'll do a copy edit pass, and ask clarifying questions.
 4. ❓The doc author/owner should answer the questions asked in the review phase. Either the doc author, or the docs team member can resolve comments as they are clarified in the doc text.👍
@@ -76,8 +76,6 @@ If you're planning substantial changes to the docs, follow this process for grea
 
 Once the PR is merged, the docs site rebuilds and the changes are live!
 
-(* The docs team is just Laura right now.)
-
 
 ### The Docs Process for direct contributors
 
@@ -88,17 +86,16 @@ Once the PR is merged, the docs site rebuilds and the changes are live!
 3. Commit your changes.
 3. Push the branch to `segment-docs` and make a PR to master.
     - Include any context you can in the PR: links to ZD tickets, Jira tickets, Paper docs or wiki pages about the project. (If you include a Jira ticket number, Jira can often link directly to the PR.)
-3. [Check if you need a review](#most-frequently-asked-question-do-i-need-a-review) and tag @sanscontext (or another member of the docs team). (Github also tags the CODEOWNERS for the path you're editing.)
+3. [Check if you need a review](#most-frequently-asked-question-do-i-need-a-review) and tag a member of the docs team. (Github also tags the CODEOWNERS for the path you're editing.)
 5. If the reviewers ask for clarifications or edits:
     - make the changes
     - push the new commits to the branch
 5. Once you get an approving review and the checks pass, merge your PR.
-6. Once you've merged the branch, _delete it_!
-7. Once merged, you can track build and deploy process in [buildkite/segment-docs](https://buildkite.com/segment/segment-docs).
+7. Once merged, Netlify builds the changes to `master` and redeploys the docs site.
 
 ### Draft PRs
 
-If you're doing a substantial change and you're going to want to spend a few weeks on it, use [Github's Draft PRs feature](https://help.github.com/en/articles/about-pull-requests#draft-pull-requests), or add `WIP` to the title of your PR. This lets us know to ignore the PR until you're ready (otherwise Laura will ping you weekly about it!).
+If you're doing a substantial change and you're going to want to spend a few weeks on it, use [Github's Draft PRs feature](https://help.github.com/en/articles/about-pull-requests#draft-pull-requests), or add `DRAFT` or `WIP` to the title of your PR. This lets us know to ignore the PR until you're ready (otherwise we might ping you weekly about it!).
 
 
 ## How the docs build works
@@ -111,10 +108,10 @@ When you run `make dev` (or `make docs`) on your laptop, Jekyll runs the same pr
 
 Some of these files include Liquid script, which allows them to load reusable content ("includes"), render fancy HTML styling, and run simple code processes to build programmatic content. As long as the Jekyll process is running on your laptop, you can edit the content of a page in markdown and save it, and Jekyll will detect the change and rebuild that page so you can view it locally. However, this doesn't work if you're editing the page layouts or stylesheets, which are assumed to be static at build time.
 
-When you merge a PR to master, our build system runs the Jekyll program, and automatically publishes the rebuilt HTML files to our web server. (Which is why we *require* that the Buildkite build passes before you merge!)
+When you merge a PR to master, the Netlify build system runs the Jekyll program, and automatically publishes the rebuilt HTML files.
 
 ## Formatting and Prettifying
-Some important tips are in the [styleguide](styleguide.md). We also have a (rendering)[Formatting guide](/src/utils/formatguide.md) available so you can see how different formatting looks when rendered.
+Some important tips are in the [styleguide](styleguide.md). We also have a (rendering) [Formatting guide](/src/utils/formatguide.md) available so you can see how different formatting looks when rendered.
 
 ## Repo structure
 
@@ -147,15 +144,13 @@ A few possibilities/suggestions:
 - **Name images to describe a process flow**. For example `checkout-1-add-to-cart.png`, `checkout-2-est-shipping.png` and so on.
 
 
-### Diagram Library
-
-We have a diagram library in Sketch, which you can use to build pretty, on-brand architecture diagrams, etc. There's a [readme file in that directory](diagram-library/readme.md) with instructions on how to use it.
-
 ### Content structure
 
 There are folders for each of the top level products, and those folders might also contain topics that are related to that product area (for example the Privacy Portal section also contains GDPR/CCPA docs).
 
-For the Connections product, the section is divided into the Spec, then Sources, Destinations, and Warehouses, with general accessory topics at the folder root. (More specific accessory topics are in each sub directory.) Each also contains a `catalog` directory, which contains all the directories with information about specific integrations. The top-level of this folder (the `index.md`) is a pretty "catalog" page which gives a tile-like view by category, suitable for browsing. It pulls the logo for these tiles from the path for the integration in the metadata service.
+For the Connections product, the section is divided into the Spec, then Sources, Destinations, and Storage Destinations (formerly called "Warehouses"), with general accessory topics at the folder root. (More specific accessory topics are in each sub directory.)
+
+Each also contains a `catalog` directory, which contains all the directories with information about specific integrations. The top-level of this `catalog` folder (the `index.md`) is a pretty "catalog" page which gives a tile-like view by category, suitable for browsing. It pulls the logo for these tiles from the path for the integration in the metadata, either in `destinations.yml`, `sources.yml`, or `warehouses.yml`.
 
 
 ### Programmatic content
@@ -166,7 +161,7 @@ Programmatic content is built using information in the files in `/src/_data/cata
 
 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`.
 
-Destination pages include the `integration_foot.md` content which uses Liquid scripting and pulls from the catalog metadata.
+Destination pages include the `destination-dossier.html` and `destination_footer.md` content, which use Liquid scripting and pulls from the catalog metadata.
 
 Sources pages check if the source is a cloud-app, then include information about if the source is an object or event source, based on the `type` data from the ConfigAPI.
 
@@ -223,14 +218,10 @@ We have two neat icons that you can add to a bottom-level menu item to mark it w
 - `dev`: runs `jekyll serve` locally with incremental builds. Useful when updating CSS, JS, or content and you don't want to rebuild every time.
 - `docs`: same as `make dev`, but for Laura's convenience.
 - `build`: Builds the site docs. Used by CI to publish the docs to staging and production
-- `catalog`: Pulls in the latest catalog data from the Platform API and saves it in the respective data files. Requires an API key to be passed in env via PLATFORM_API_TOKEN. [Instructions here](#bring-your-own-token).
+- `catalog`: Pulls in the latest catalog data from the Platform API and saves it in the respective data files. Requires an API key to be passed in env via PLATFORM_API_TOKEN. [Instructions here](https://github.com/segmentio/segment-docs/blob/master/contributors.md#refresh-the-segment-catalog).
 - `sidenav`: Builds the side navs for 'main', 'legal', 'api', 'partners' and stores the output in `/src/_data/sidenav-auto/`. This output isn't used for the actual build.
 - `typewriter`: pulls in the current state of the Docs tracking plan for implementing Segment tracking
 - `seed`: copies all example data files out of the `_templates` directory and puts them in the `_data` directory. Useful if you don't have a way to set up an API key.
 - `clean`: removes all build artifacts
 - `clean-deps`: removes all downloaded `gems` and `node_modules`
 - `deps`: installs the required `gems` and `node_modules`
-
-
-- docker-build: runs `make build` on a docker host.
-- docker-dev: runs `make dev` on a docker host.

contributors.md

@@ -4,6 +4,25 @@ Thanks for helpin' out! We really appreciate it.
 
 ![](guide-imgs/segment-sloth-heart.png)
 
+Here's what's here:
+<!-- TOC depthFrom:2 depthTo:6 withLinks:1 updateOnSave:1 orderedList:0 -->
+
+- [Contribute from the Github web UI](#contribute-from-the-github-web-ui)
+- [Contribute using Git and Atom](#contribute-using-git-and-atom)
+	- [Making review edits in a PR](#making-review-edits-in-a-pr)
+- [Contribute using git native commands](#contribute-using-git-native-commands)
+- [Tips and tricks](#tips-and-tricks)
+	- [Adding links that open in a new window](#adding-links-that-open-in-a-new-window)
+	- [Escaping code snippets](#escaping-code-snippets)
+	- [Syntax highlighting](#syntax-highlighting)
+	- [Note Blocks](#note-blocks)
+	- [Redirect to a workspace](#redirect-to-a-workspace)
+- [Set up on Mac using the Env script](#set-up-on-mac-using-the-env-script)
+- [Refresh the Segment catalog](#refresh-the-segment-catalog)
+	- [Set up to refresh the Segment catalog](#set-up-to-refresh-the-segment-catalog)
+
+<!-- /TOC -->
+
 
 There are three ways to contribute.
 - EASY: [Contribute from the Github web UI](#contribute-from-the-github-web-ui) - only use this when making small edits to existing text files
@@ -36,7 +55,7 @@ This guide also contains a bunch of [useful formatting tips and tricks](#tips-an
 6. Once someone has reviewed and approved the change,  merge the change.
 7. Delete the branch once the change has been merged!
 
-**If changes are needed on your Github PR**: You (or they) can add Github "suggestions", which you can merge into your PR one by one. If there are many updates, you might need to check out your branch using the Atom and Git process below to make the changes in a single commit.
+**If changes are needed on your Github PR**: You (or they) can add Github "suggestions", which you can merge into your PR either in a batch, or one by one. If there are many updates, you might need to check out your branch using the Atom and Git process below to make the changes in a single commit.
 
 ## Contribute using Git and Atom
 
@@ -95,7 +114,7 @@ This section is a very sparse outline of a git flow for git-experts and other fo
 6. Push your branch and changes to the `segment-docs` repo (`git push`, `git push --set-upstream origin`)
 7. Repeat steps 3-6 as needed.
 8. Open a PR by [going to the PRs page](https://github.com/segmentio/segment-docs/pulls), if not prompted, create new by selecting `master` as base, `(your branch name)` as other.
-9. Request a review. The Codeowners should populate this, and if not you can tag @sanscontext.
+9. Request a review. The Codeowners should populate this, and if not you can tag someone on the docs team.
 10. If changes are requested, repeat steps 3-6 as needed.
 11. Once approved, merge and delete branch, delete branch locally.
 
@@ -110,7 +129,7 @@ To make a link open in a new tab append `[text](https://example.com){:target="_b
 
 ### Escaping code snippets
 
-Certain code syntax will be interpreted by Jekyll/Liquid as site code. If you're having trouble showing code snippets in the docs, you can wrap the snippet in a `{% raw %}` tag. In the example below, the curly brackets would not render in the docs. The raw tags ensure the code renders properly.
+Certain code syntax is interpreted by Jekyll/Liquid as site code. If you're having trouble showing code snippets in the docs, you can wrap the snippet in a `{% raw %}` tag. In the example below, the curly brackets would not render in the docs. The raw tags ensure the code renders properly.
 
 ```
 {% raw %}
@@ -134,17 +153,18 @@ You'd write a block like this:
 ```
 
 Notes *must* include a `[]` in the heading/title, even if it's empty.
-You can see how to write them in the `styleguide.md`, and see how they render at [https://segment.build/docs/styleguide](https://segment.build/docs/styleguide)
+You can see how to write them in the `formatguide.md`, and see how they render at [https://segment.com/docs/utils/formatguide/#alerts](https://segment.com/docs/utils/formatguide/#alerts). This section also includes instructions on when to use each one.
 
 ### Redirect to a workspace
-Occasionally, you'll want to deep-link into the Segment app to link a reader to a specific page or screen. Previously we'd throw them an URL and say "replace {MY SLUG} with your actual workspace slug", but now you can use the slug of `goto-my-workspace` and the Segment app will redirect them.
+Occasionally, you'll want to deep-link into the Segment app to link a reader to a specific page or screen. Previously we'd throw them an URL and say "replace {MY SLUG} with your actual workspace slug", but now you can use the slug of `goto-my-workspace` and the Segment app will redirect them to the first workspace they have access to. (This does mean that it can go a bit wrong for users with access to multiple workspaces, however that's a small proportion of our users at this time.)
+
 https://app.segment.com/goto-my-workspace/destinations/catalog
 
 
 
 ## Set up on Mac using the Env script
 
-We've written a bash script to set up the environment for you on a Mac computer. If you're on another platform, please [email us](mailto:[email protected]) or [file a Github Issue](https://github.com/segmentio/segment-docs/issues/new) to request other instructions, and we'll see what we can do.
+Laura wrote a bash script to set up the environment for you on a Mac computer. If you're on another platform, please [email us](mailto:[email protected]) or [file a Github Issue](https://github.com/segmentio/segment-docs/issues/new) to request other instructions, and we'll see what we can do.
 
 > info ""
 > You only need to run `make env` once!
@@ -155,7 +175,7 @@ We've written a bash script to set up the environment for you on a Mac computer.
 4. Start by checking what directory you’re in, to make sure you’re in the `segment-docs` repo.
    Type `pwd` (which means “print working directory”) to check. You should see something like `~/repos/segment-docs`.
 5. Type `make env`.
-   The script first checks to see if you have Brew installed, and if you don’t, it installs it. It then runs more brew commands to download and install the software you need.
+   The script first checks to see if you have [Brew](https://brew.sh) installed, and if you don’t, it installs it. It then runs more brew commands to download and install the software you need, including a bunch of really useful Atom packages.
 
    > **Heads up**! You’re going to need to enter your laptop password as part of this installation, but only once!
 
@@ -166,13 +186,15 @@ We've written a bash script to set up the environment for you on a Mac computer.
     Go to **Preferences > Editor**, and scroll down to **Show Invisibles**. Make sure that’s checked!
     ![](guides-img/show-invisibles.png)
 
+
+<!-- LR: This stopped working when Apple switched to Zshell by default, and I haven't been able to get it working since.
 8.  Finally, configure bash completion by adding tab-completion to your `.bash` profile:
 
     1. Open Terminal and type `atom ~/.bash_profile` to open the file in Atom.
     2. Paste the following anywhere in the file:
     `[[ -r "/usr/local/etc/profile.d/bash_completion.sh" ]] && . "/usr/local/etc/profile.d/bash_completion.sh"`
     3. Save and close the file in Atom.
-    4. Quit and relaunch both Terminal and Atom.
+    4. Quit and relaunch both Terminal and Atom.-->
 
 ## Refresh the Segment catalog
 
@@ -182,14 +204,15 @@ To update the files, you run `make catalog` from your Terminal.  Before you can
 
 ### Set up to refresh the Segment catalog
 
-To use the `make catalog` command to update the list of sources and destinations that Segment supports, you'll need [a basic token for the Segment ConfigAPI](https://segment.com/docs/config-api/authentication/). You'll save this in a `.env` file on your computer, which will allow the script to talk to the Segment APIs.
+To use the `make catalog` command to update the list of sources and destinations that Segment supports, you'll need [a basic token for the Segment ConfigAPI](https://segment.com/docs/config-api/authentication/). You'll save this in a `.env` file on your computer, which allows the script to talk to the Segment APIs.
 
 1. If you don't already have one, sign up for a free Segment workspace.
 2. Copy the `.env.example` file at the root of this directory, and rename it to remove the word "example". It should *just* be called `.env` when you're done. **Do NOT check in your .env file.**
 2. Go to the workspace's **Settings > Access Management > Tokens** tab (or click [here](https://app.segment.com/goto-my-workspace/settings/access-management)).
 3. Click **Create Token**.
-4. Add a description (you and specify that you're using it for docs purposes).
-5. Select **Workspace Member**, check **Source Admin**, and select one or all sources. You can grant this token more privileges, but that is unnecessary for this use.
+4. Add a description (and specify that you're using it for docs purposes, so nobody revokes it accidentally).
+5. Select **Workspace Member**, check **Source Admin**, and select one or all sources. You _can_ grant this token more privileges, but that's unnecessary.
 5. Click **Create**.
-6. Copy the token payload, and paste it after the equals sign (`=`) after "PLATFORM_API_TOKEN".
-7. Save and close the file. Before running the make command you may need to type `env` and enter into Terminal, or otherwise restart your Terminal session.
+6. Copy the token, and paste it after the equals sign (`=`) after "PLATFORM_API_TOKEN".
+7. Save and close the file.
+   Before you run the make command you might need to type `env` and enter into Terminal, or otherwise restart your Terminal session.