chore:align docs with the rest of apps

.tool-versions

@@ -0,0 +1 @@
+ruby 2.7.5

README.md

@@ -3,207 +3,18 @@
 The Artsy OSS page and the blog runs on top of a default jekyll install. If you
 would like an overview of jekyll, their [website rocks](http://jekyllrb.com/).
 
-## Setup
+## Documentation
 
-```
-git clone [email protected]:artsy/artsy.github.io.git
-cd artsy.github.io
-bundle
-bundle exec rake bootstrap
-bundle exec rake build
-```
-
-### Common issues ⚠️
-
-<details><summary>Issues installing `therubyracer` and/or `v8` dependencies</summary>
-Some combination of the following might help resolve issues with installing these dependencies:
-
-- make sure you have a ruby version that works (e.g. 2.7.5)
-- Installing `v8` via homebrew: `brew install v8`
-- Installing the `libv8` gem using a specific version and v8 flag:
-  `gem install libv8 -v '3.16.14.19' -- --with-system-v8`
-- Assigning configuration options, as in
-  [this comment](https://gist.github.com/fernandoaleman/868b64cd60ab2d51ab24e7bf384da1ca#gistcomment-3114668).
-
-</details>
+- [Getting Started](docs/getting_started.md) - Setup, running locally, and deploying
+- [Authoring Articles](docs/authoring_articles.md) - Writing blog posts, adding authors, and enabling comments
+- [Authoring Podcasts](docs/authoring_podcasts.md) - Adding podcast episodes
 
 ## License
 
 The code in this repository is released under the MIT license. The contents of
 the blog itself (ie: the contents of the `_posts` directory) are released
 under +[Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/).
 
-## Running the OSS Site / Blog locally
-
-Running `rake serve` will _not_ generate category pages. They take a _long_ time
-to generate. No one wants that when working on the site.
-
-```
-  bundle exec rake serve
-```
-
-Categories are generated when the ENV var `PRODUCTION` = `"YES"`.
-
-## Deploying
-
-- Circle automatically deploys to GitHub Pages when new commits are pushed to
-  the `source` branch.
-- If you need to trigger a deploy locally, the `rake deploy` command is
-  available.
-- See the `Rakefile` for details on how builds/deploys are done.
-- Note that the `main` branch does not build on Circle, due to all deploy
-  commits being prefixed with `[skip ci]`.
-
-## Adding an Author
-
-Authors are key-value stored, so you will need to give yourself a key inside
-[\_config.yml](_config.yml) - for example:
-
-```yaml
-joey:
-  name: Joey Aghion
-  github: joeyAghion
-  twitter: joeyAghion
-  site: http://joey.aghion.com
-```
-
-Everything but name is optional.
-
-## Authoring an Article
-
-Note: we now have some templates to help get you started writing a blog post.
-Check out the [`Post-Templates` directory](Post-Templates).
-
-TLDR _To generate a new post, create a new file in the `_posts` directory. Be
-sure to add your name as the author of the post and include several categories
-to file the post under. Here is a sample header YAML:_
-
-Note: categories are aggregated from the individual posts, so adding one is as
-easy as adding it to your post!
-
-```yaml
----
-layout: post
-title: "Responsive Layouts with CSS3"
-date: 2012-01-17 11:03
-comments: true
-author: Matt McNierney
-github-url: https://www.github.com/mmcnierney14
-twitter-url: http://twitter.com/mmcnierney
-blog-url: http://mattmcnierney.wordpress.com
-categories: [Design, CSS, HTML5]
----
-```
-
-More info can be found in the [Jekyll docs](http://jekyllrb.com/docs/posts/).
-
-When you have authored an article, `git add` and `git commit` it, then push to a
-named branch with `git push origin [branch]`, and create a pull request to the
-`source` branch, it will be deployed to the site by travis when merged.
-
-After you have authored an article, consider re-generating the related articles
-data, so that we can surface other articles related to the one you just added.
-See **Generating related articles** section below.
-
-## Enabling Comments
-
-Comments for articles are managed with
-[Issues](https://github.com/artsy/artsy.github.io/issues) in this GitHub
-repository.
-
-#### [Create an issue](https://github.com/artsy/artsy.github.io/issues/new) for the article
-
-Quote the opening paragraph(s) of the post as the body of the issue, and name it
-something like "Comments: My Fantastic New Post".
-
-#### Add the `Comment Thread` label to the issue
-
-#### Attach the issue to your article
-
-Copy the created issue ID; add it to the frontmatter YAML of your post, as the
-`comment_id` attribute:
-
-`comment_id: 1234`
-
-## After Deploying an Article
-
-Every article on our blog needs one more thing: a snappy tweet! You can ask Ash
-or Orta to do this for you, but you're also welcome to log into the
-[@ArtsyOpenSource](https://twitter.com/ArtsyOpenSource) twitter account and
-tweet yourself (credentials are in the Engineering 1Password vault). Tweets
-usually follow the following format:
-
-```
-[pithy observation] [description of problem] [@ the article author's twitter handle]
-
-📝 [link to blog post]
-💻 [link to GitHub repo, if applicable]
-📷 [attach a screenshot of the first few paragraphs of the post]
-```
-
-We attach screenshots of the post because tweets with images get more traction.
-But! Images aren't accessible to screen readers, so make sure to use the
-twitter.com web interface and add a description to the image when posting:
-
-> Screenshot of the title and first two paragraphs of the linked-to blog post.
-
-You can look at previous tweets from our account to get a feel for these. If
-you'd like help, just ask in Slack.
-
-## Authoring a Podcast Episode
-
-To add a new episode of the podcast,
-[configure](https://github.com/aws/aws-sdk-ruby#configuration) your local AWS
-environment. The easiest is in environment variables stored in `~/.zshrc` or
-equivalent.
-
-```
-export AWS_ACCESS_KEY_ID=
-export AWS_SECRET_ACCESS_KEY=
-```
-
-After you have set up the environment, run the following rake task.
-
-```sh
-rake podcast:new_episode /path/to/local/mp3
-```
-
-This will add required YAML to `_config.yml`. You'll need to fill in some other
-fields manually; when finished it'll look like this:
-
-```yaml
-- title: Name of your episode
-  date: (generated by Rake task)
-  description: A paragraph-long description of the episode.
-  podcast_url: (generated by Rake task)
-  file_byte_length: (generated by Rake task)
-  duration: (generated by Rake task)
-```
-
-## Generating related articles
-
-Generating the content for the "related articles" section at the bottom of an
-article is an offline & manual process that makes use of our staging vector
-database.
-
-Any developer can run this at any time and commit the resulting changes to
-`related-articles.json`.
-
-There are a few simple prerequisite steps required for this task specifically:
-
-1. `gem install foreman`, if you haven't already.
-
-2. `cp .env.example .env`, if you haven't already.
-
-3. Connect to the staging VPN in order to access the staging instance of
-   Weaviate, our vector database.
-
-After that it is just:
-
-```sh
-foreman run bundle exec rake related_articles
-```
-
 ## About Artsy
 
 <a href="https://www.artsy.net/">

docs/authoring_articles.md

@@ -0,0 +1,106 @@
+# Authoring Articles
+
+- [Authoring Articles](#authoring-articles)
+  - [1. Adding an Author](#1-adding-an-author)
+  - [2. Creating a Post](#2-creating-a-post)
+  - [3. Submitting Your Post](#3-submitting-your-post)
+  - [4. Enabling Comments](#4-enabling-comments)
+  - [5. After Deploying](#5-after-deploying)
+  - [6. Generating Related Articles](#6-generating-related-articles)
+
+---
+
+## 1. Adding an Author
+
+Authors are key-value stored in [\_config.yml](../_config.yml). Add yourself with a key:
+
+```yaml
+joey:
+  name: Joey Aghion
+  github: joeyAghion
+  twitter: joeyAghion
+  site: http://joey.aghion.com
+```
+
+Everything but name is optional.
+
+## 2. Creating a Post
+
+Create a new file in the `_posts` directory. Templates are available in the [`Post-Templates`](../Post-Templates) directory.
+
+Include this YAML header:
+
+```yaml
+---
+layout: post
+title: "Responsive Layouts with CSS3"
+date: 2012-01-17 11:03
+comments: true
+author: Matt McNierney
+github-url: https://www.github.com/mmcnierney14
+twitter-url: http://twitter.com/mmcnierney
+blog-url: http://mattmcnierney.wordpress.com
+categories: [Design, CSS, HTML5]
+---
+```
+
+Categories are aggregated from individual posts - adding a new one is as easy as including it in your post.
+
+More info in the [Jekyll docs](http://jekyllrb.com/docs/posts/).
+
+## 3. Submitting Your Post
+
+```bash
+git add .
+git commit -m "Add blog post: Your Title"
+git push origin your-branch
+```
+
+Create a PR to the `source` branch. It will be deployed when merged.
+
+After authoring, consider [regenerating related articles](#6-generating-related-articles).
+
+## 4. Enabling Comments
+
+ _(optional)_
+Comments are managed with [GitHub Issues](https://github.com/artsy/artsy.github.io/issues).
+
+1. [Create an issue](https://github.com/artsy/artsy.github.io/issues/new) - quote the opening paragraph(s) and name it "Comments: My Fantastic New Post"
+2. Add the `Comment Thread` label
+3. Add `comment_id: <issue-number>` to your post's front matter
+
+## 5. After Deploying
+
+Tweet from [@ArtsyOpenSource](https://twitter.com/ArtsyOpenSource) (credentials in Engineering 1Password vault):
+
+```
+[pithy observation] [description of problem] [@ author's twitter]
+
+[link to blog post]
+[link to GitHub repo, if applicable]
+[attach a screenshot of the first few paragraphs]
+```
+
+Add image description for accessibility:
+
+> Screenshot of the title and first two paragraphs of the linked-to blog post.
+
+## 6. Generating Related Articles
+
+_(optional)_
+
+The "related articles" section is generated offline using our staging vector database.
+
+**Prerequisites**
+
+1. Install foreman: `gem install foreman`
+2. Copy environment file: `cp .env.example .env`
+3. Connect to the staging VPN to access Weaviate (our vector database)
+
+**Generate**
+
+```sh
+foreman run bundle exec rake related_articles
+```
+
+Commit the resulting changes to `related-articles.json`.

docs/authoring_podcasts.md

@@ -0,0 +1,29 @@
+# Authoring Podcast Episodes
+
+## Setup
+
+[Configure](https://github.com/aws/aws-sdk-ruby#configuration) your local AWS environment. Add to `~/.zshrc` or equivalent:
+
+```
+export AWS_ACCESS_KEY_ID=
+export AWS_SECRET_ACCESS_KEY=
+```
+
+## Adding an Episode
+
+Run:
+
+```sh
+rake podcast:new_episode /path/to/local/mp3
+```
+
+This adds required YAML to `_config.yml`. Fill in the remaining fields:
+
+```yaml
+- title: Name of your episode
+  date: (generated by Rake task)
+  description: A paragraph-long description of the episode.
+  podcast_url: (generated by Rake task)
+  file_byte_length: (generated by Rake task)
+  duration: (generated by Rake task)
+```

docs/getting_started.md

@@ -0,0 +1,44 @@
+# Getting Started
+
+## Setup
+
+```
+git clone [email protected]:artsy/artsy.github.io.git
+cd artsy.github.io
+bundle
+bundle exec rake bootstrap
+bundle exec rake build
+```
+
+<details>
+<summary>Common Issues</summary>
+
+### Issues installing `therubyracer` and/or `v8` dependencies
+
+Some combination of the following might help:
+
+- Make sure you have a ruby version that works (e.g. 2.7.5)
+- Installing `v8` via homebrew: `brew install v8`
+- Installing the `libv8` gem using a specific version and v8 flag:
+  `gem install libv8 -v '3.16.14.19' -- --with-system-v8`
+- Assigning configuration options, as in
+  [this comment](https://gist.github.com/fernandoaleman/868b64cd60ab2d51ab24e7bf384da1ca#gistcomment-3114668).
+
+</details>
+
+## Running Locally
+
+Running `rake serve` will _not_ generate category pages. They take a _long_ time to generate.
+
+```
+bundle exec rake serve
+```
+
+Categories are generated when the ENV var `PRODUCTION` = `"YES"`.
+
+## Deploying
+
+- Circle automatically deploys to GitHub Pages when new commits are pushed to the `source` branch.
+- If you need to trigger a deploy locally, the `rake deploy` command is available.
+- See the `Rakefile` for details on how builds/deploys are done.
+- Note that the `main` branch does not build on Circle, due to all deploy commits being prefixed with `[skip ci]`.