docs: Clean-up README

.github/ISSUE_TEMPLATE/dependency_rfc_template.md

@@ -1,6 +1,6 @@
 ---
-name: Dependency RFC
-about: Sample template for a dependency RFC
+title: Dependency RFC
+description: Sample template for a dependency RFC
 ---
 
 ### New Dependency

.github/ISSUE_TEMPLATE/generic_rfc_template.md

@@ -1,27 +1,24 @@
 ---
-name: RFC
-about: Sample template for how to create a public RFC
-
+title: RFC
+description: Sample template for how to create a public RFC
 ---
 
 <!-- Read the docs about [how to write an RFC at Artsy](https://github.com/artsy/README/blob/43c400d81ff9fee7276c3dd934de26b985da362f/playbooks/rfcs.md) before starting an RFC.
  -->
- 
+
 ## Proposal
 
 Apply a spell checker to every markdown document that appears in a PR.
 
 ## Reasoning
 
-We want to have polished documents, both internally and externally. Having a spellcheck
-happening without any effort on a developers part means that we'll get a second look at
-any documentation improvements on any repo.
+We want to have polished documents, both internally and externally. Having a spellcheck happening without any
+effort on a developers part means that we'll get a second look at any documentation improvements on any repo.
 
 ## Exceptions
 
-This won't be perfect, but it is better to get something working than to not have it at all.
-I added the ability to ignore files: so CHANGELOGs which tend to be really jargon heavy will
-be avoided in every repo.
+This won't be perfect, but it is better to get something working than to not have it at all. I added the ability to
+ignore files: so CHANGELOGs which tend to be really jargon heavy will be avoided in every repo.
 
 Other than that, we can continue to build up a global list of words to ignore.
 
@@ -33,9 +30,9 @@ You can see our discussion [in slack here](/link/to/slack.com)
 
 A PR to peril-settings adding the check
 
-<!-- 
-Things to do after you create the RFC: 
- 
+<!--
+Things to do after you create the RFC:
+
 - Publicise it. Post it on the different slack dev channels, talk about it in meetings, etc.
 - Wait for some time to make sure as many people as possible have seen it and collect feedback
 - Although encouraged, not everyone has to interact. A lack of response is assumed to be positive indifference.

CONTRIBUTING.md

@@ -2,38 +2,42 @@
 
 This project is work of [many contributors](https://github.com/artsy/README/graphs/contributors).
 
-If you work at [Artsy](https://www.artsy.net), you're encouraged to submit
-[pull requests](https://github.com/artsy/README/pulls), [propose and discuss
-issues](https://github.com/artsy/README/issues).
+If you work at [Artsy](https://www.artsy.net), you're encouraged to
+[submit pull requests](https://github.com/artsy/README/pulls),
+[propose and discuss issues](https://github.com/artsy/README/issues).
 
-If you don't work at Artsy, we would love for you to [ask us a question or highlight
-an issue](https://github.com/artsy/README/issues) in our processes, check out
-[our Engineering blog](https://artsy.github.io) or [maybe even consider working with
-us](https://www.artsy.net/jobs) :)
+If you don't work at Artsy, we would love for you to
+[ask us a question or highlight an issue](https://github.com/artsy/README/issues) in our processes, check out
+[our Engineering blog](https://artsy.github.io) or maybe even consider
+[working with us](https://www.artsy.net/jobs). :)
 
-## Editing README
+## Getting Started
 
-You can edit files via the GitHub interface if you're just trying to quickly make a change. If you want to make a
-change that is a bit more nuanced, you can clone the repo and set it up with:
+Clone the repo and set it up with:
 
 ```sh
 git clone https://github.com/artsy/README.git
 cd README
 yarn install
-
-code .
 ```
 
 ## Helpful Automation
 
-This repo has some useful automation set up for it to generate tables of contents. This is implemented in
-[`scripts/create-readmes.ts`](scripts/create-readmes.ts), which handles:
+This repo has automation that:
 
-- Creating a summary `README.md` for each section of docs
-- Providing an overview of the section in the root `README.md`
-- Enables running [doctoc](https://github.com/thlorenz/doctoc#readme) on any file with `<!-- START doctoc`
+- Automatically generates table of contents for markdown files
+- Creates summary `README.md` files for each documentation section
+- Tracks missing documentation with `[TODO]` items in pull request comments
+
+This automation runs on every commit to keep documentation organized and up-to-date.
 
-This script runs on every commit, so we'll always ensure all the table of contents are up-to-date.
+### How Automation Works
+
+The automation is implemented in [`scripts/create-readmes.ts`](scripts/create-readmes.ts), which:
+
+- Creates a summary `README.md` for each section of docs
+- Provides an overview of the section in the root `README.md`
+- Enables running [doctoc](https://github.com/thlorenz/doctoc#readme) on any file with `<!-- START doctoc`
 
 Each markdown file in a section uses [yaml front-matter](https://jekyllrb.com/docs/frontmatter/) to add a
 description and title to the document, which are used to generate a `README.md` for each section.

README.md

@@ -1,24 +1,19 @@
 # Artsy Engineering [![CircleCI](https://circleci.com/gh/artsy/README.svg?style=svg)](https://circleci.com/gh/artsy/README)
 
-Welcome to Artsy! If you're a new team member, we're excited to have you! Here are your
-[onboarding docs](/onboarding#readme).
+Welcome to Artsy! If you're a new team member, we're excited to have you! Here are your [onboarding docs](/onboarding#readme).
 
-This repo is a work in progress. In fact, your first pull request could be to fix or add to
-[this doc](https://github.com/artsy/README/blob/master/README.md). Reach out to your mentor or anyone else on the
-engineering team with questions, or try the [#dev Slack channel](https://artsy.slack.com/messages/dev) 🔒.
+This repo is a work in progress. In fact, your first pull request could be to fix or add to [this doc](/README.md). Reach out to your mentor or anyone else on the engineering team with questions, or try the [#dev Slack channel](https://artsy.slack.com/messages/dev) 🔒.
 
-Whether you're seasoned or fresh out of school, take a moment to read
-[Your First 60 Days at an Engineering Job](https://code.dblock.org/2015/04/23/your-first-60-days-at-an-engineering-job.html).
+Whether you're seasoned or fresh out of school, take a moment to read [Your First 60 Days at an Engineering Job](https://code.dblock.org/2015/04/23/your-first-60-days-at-an-engineering-job.html).
 
 We split this repo out into different sections, each one has a summary of what's inside to make it easy to browse.
 
 <!-- prettier-ignore-start -->
 <!-- start_toc -->
 | Section |  |
 |--|--|
-| [[TODO] Add a summary.json to RFCs](/RFCs) | [TODO] |
+| [Requests for Comments (RFCs)](/RFCs#readme) | Engineering-wide proposals that require discussion and feedback before implementation. |
 | [Careers at Artsy](/careers#readme) | How do we grow people |
-| [Conference Notes](/conference-notes#readme) | Artsy Engineers' notes from attending conferences. |
 | [Engineering Culture](/culture#readme) | What makes Artsy Engineering tick? |
 | [Events at Artsy](/events#readme) | Documentation on regularly occurring events and meetings. |
 | [Hiring at Artsy](/hiring#readme) | How do we hire people |
@@ -31,16 +26,11 @@ We split this repo out into different sections, each one has a summary of what's
 
 ## Artsy Engineering Operations
 
-### Product & Engineering Teams
+### Teams
 
-Artsy product engineering is organized in product teams. Each team has a _purpose_, eg. _"Help galleries get the
-most out of Artsy and run their business better"_, and Key Performance Indicators, or KPIs, eg. _"The number of
-artworks uploaded by partners."_ Each team has members with different responsibilities, including a _Product
-Manager_, a _Designer_, a _Technical Lead_ and _Engineers_, depending on size. Sometimes the same person wears
-multiple hats.
+Teams at Artsy are cross functional. A regular team being composed of a Product Manager, a Product Designer, a Data Analyst, an Engineering Manager and Engineers. Each team has a _mission_, eg. _"From negotiation to fulfillment, Emerald aims to facilitate an enjoyable, consistent, secure, and global deal-closure experience that leaves collectors, sellers, and Artsy Admin eager to return."_, and quarterly goals aligned with our company objectives.
 
-You can see this organization
-[in the Product section of Notion 🔑](https://www.notion.so/artsy/Product-470238180cf94c87906ef1d3ee259e05).
+You can see this organization [in the PDDE section of Notion 🔒](https://www.notion.so/artsy/c729f52babc34f59bf47dbfbe2456d19?v=184cab0764a080d38737000c1da4917d).
 
 In addition to working on a product team, engineers are encouraged to participate in our practices:
 
@@ -52,8 +42,7 @@ In addition to working on a product team, engineers are encouraged to participat
 
 - Mobile Practice
 
-  - Practice co-leads: [George Kartalis](https://github.com/gkartalis) and
-    [Sultan Al-Maari](https://github.com/MrSltun)
+  - Practice co-leads: [George Kartalis](https://github.com/gkartalis) and [Sultan Al-Maari](https://github.com/MrSltun)
   - [Slack: #practice-mobile](https://artsy.slack.com/messages/practice-mobile) 🔒
   - [Notion](https://www.notion.so/artsy/Mobile-Practice-ecc07763bfd04a848c74107dde3ec6dc) 🔒
 
@@ -63,25 +52,9 @@ In addition to working on a product team, engineers are encouraged to participat
   - [Slack: #practice-web](https://artsy.slack.com/messages/practice-web) 🔒
   - [Notion](https://www.notion.so/artsy/Web-Practice-bfe55e2c614a4c0eae493b7830622843) 🔒
 
-- Data Practice
-  - Practice lead: [Anil Bawa-Cavia](https://github.com/cavvia)
-  - [Slack: #practice-data](https://artsy.slack.com/messages/practice-data) 🔒
-  - [Notion](https://www.notion.so/artsy/Data-Practice-e248b46638604067a89ba77ca70b39b1) 🔒
-
-## Request For Comments
-
-A Request For Comments (or RFC) is how we change things, by opening a discussion that everyone can participate in
-and deciding if we want to move forward with the suggested change or not.
-
-RFCs should be created by authoring a markdown file in the `/RFCs` folder and then opening a pull request. [Read
-the full playbook][rfc_playbook] for all the details!
-
-[rfc_playbook]: /playbooks/rfcs.md
-
 ## Support
 
-If you are on call or asked to fix an immediate issue reference our
-[support wiki](https://github.com/artsy/potential/wiki) 🔒 for up-to-date playbooks on how to solve issues.
+If you are on call or asked to fix an immediate issue reference our [engineering playbooks](https://www.notion.so/artsy/Engineering-Playbooks-b655fe54c1ce4b35af342c9ed9a489ae) 🔒 for up-to-date solutions to potential issues.
 
 <a rel="license" href="https://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a>
 
@@ -91,17 +64,11 @@ If you are on call or asked to fix an immediate issue reference our
   <img align="left" src="https://avatars2.githubusercontent.com/u/546231?s=200&v=4"/>
 </a>
 
-This project is the work of engineers at [Artsy][footer_website], the world's leading and largest online art
-marketplace and platform for discovering art. One of our core [Engineering Principles][footer_principles] is being
-[Open Source by Default][footer_open] which means we strive to share as many details of our work as possible.
+This project is the work of engineers at [Artsy][footer_website], the world's leading and largest online art marketplace and platform for discovering art.
 
-You can learn more about this work from [our blog][footer_blog] and by following [@ArtsyOpenSource][footer_twitter]
-or explore our public data by checking out [our API][footer_api]. If you're interested in a career at Artsy, read
-through our [job postings][footer_jobs]!
+Learn more about us from [our blog][footer_blog] and by following [@ArtsyOpenSource][footer_twitter] or explore our public data by checking out [our API][footer_api]. If you're interested in a career at Artsy, read through our [job postings][footer_jobs]!
 
 [footer_website]: https://www.artsy.net/
-[footer_principles]: https://github.com/artsy/README/blob/master/culture/engineering-principles.md
-[footer_open]: https://github.com/artsy/README/blob/master/culture/engineering-principles.md#open-source-by-default
 [footer_blog]: https://artsy.github.io/
 [footer_twitter]: https://twitter.com/ArtsyOpenSource
 [footer_api]: https://developers.artsy.net/

RFCs/README.md

@@ -9,12 +9,12 @@ RFCs should be created by authoring a markdown file in the `/RFCs` folder and th
 <!-- prettier-ignore-start -->
 <!-- start_toc -->
 
-| Doc                                                                                                                     | Overview                                                                         |
-| ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
-| [[TODO] add title via yml front-matter to RFCs/on-call-incident-review.md](/RFCs/on-call-incident-review.md#readme)     | [TODO] add description via yml front-matter to RFCs/on-call-incident-review.md   |
-| [[TODO] add title via yml front-matter to RFCs/platform-practice-4ps.md](/RFCs/platform-practice-4ps.md#readme)         | [TODO] add description via yml front-matter to RFCs/platform-practice-4ps.md     |
-| [[TODO] add title via yml front-matter to RFCs/switch-to-standardrb.md](/RFCs/switch-to-standardrb.md#readme)           | [TODO] add description via yml front-matter to RFCs/switch-to-standardrb.md      |
-| [[TODO] add title via yml front-matter to RFCs/use-prs-instead-of-issues.md](/RFCs/use-prs-instead-of-issues.md#readme) | [TODO] add description via yml front-matter to RFCs/use-prs-instead-of-issues.md |
+| Doc | Overview |
+| --- | --- |
+| [Incident Review process for an on-call engineer](/RFCs/on-call-incident-review.md#readme) | A process for preparing and facilitating an incident review meeting while on-call |
+| [Platform Practice 4Ps](/RFCs/platform-practice-4ps.md#readme) | With this document, I am proposing a review of the platform practice using the 4Ps for meetings(Purpose, Product, Process and People) |
+| [Switch to Standard Ruby](/RFCs/switch-to-standardrb.md#readme) | Align on a single way of formatting Ruby. |
+| [Use PRs instead of Issues for RFCs](/RFCs/use-prs-instead-of-issues.md#readme) | Switching the RFC process from GitHub Issues to Pull Requests to enable inline comments and better tracking of accepted/rejected proposals. |
 
 <!-- end_toc -->
 <!-- prettier-ignore-end -->undefined