[DOC] Update DEV onboarding documentation (#4215)

docs/getting-started/branching.md

@@ -2,16 +2,22 @@
 title: Creating a Feature Branch
 ---
 
-# Creating a Feature / Bug Branch
+# Creating a feature/bug branch
 
-When you are working on a bug, feature, or improvement, you will need to create a branch. For features or improvement, you will create a branch as follows:
+When you are working on a bug, feature, or improvement, you will need to
+create a branch.
+
+Generally, it can be helpful to prefix a branch name with `feature` or `bug` to
+denote what kind of code a reviewer can expect to find on the branch.
+
+For features or improvement, you should create a branch as follows:
 
 ```
-git checkout -b feature/that-new-feature`
+git checkout -b feature/that-new-feature
 ```
 
-For a bug branch, you will do as follows:
+For a bug branch, you should do as follows:
 
 ```
-bug/fixing-that-bug
+git checkout -b bug/fixing-that-bug
 ```

docs/getting-started/committing.md

@@ -2,15 +2,15 @@
 title: Committing
 ---
 
-# Committing and Pre-Commit Hooks
+# Committing and pre-commit hooks
 
-## Style Guide
+## Style guide
 
 This project follows [thoughtbot's Ruby Style Guide](https://github.com/thoughtbot/guides/blob/master/style/ruby/.rubocop.yml), using [Rubocop](https://github.com/bbatsov/rubocop) along with [Rubocop-Rspec](https://github.com/backus/rubocop-rspec) as the code analyzer. If you have Rubocop installed with your text editor of choice, you should be up and running.
 
 For Javascript, we follow [Airbnb's JS Style Guide](https://github.com/airbnb/javascript), using [ESLint](https://eslint.org) and [prettier](https://github.com/prettier/prettier). If you have ESLint installed with your text editor of choice, you should be up and running.
 
-## Husky Hooks
+## Husky hooks
 
 When commits are made, a git precommit hook runs via [husky](https://github.com/typicode/husky) and [lint-staged](https://github.com/okonet/lint-staged). ESLint, prettier, and Rubocop will run on your code before it's committed. If there are linting errors that can't be automatically fixed, the commit will not happen. You will need to fix the issue manually then attempt to commit again.
 

docs/getting-started/config-env.md

@@ -1,23 +1,32 @@
 ---
-title: Configure Environment Variables
+title: Configuring Environment Variables
 ---
 
-# Configure environment variables/secrets
+# Configuring environment variables and secret keys
 
-Take a look at `Envfile`. This file lists all the `ENV` variables we use and provides a fake default for any missing keys. You'll need to get your own free [Algolia credentials](/backend/algolia) to get your development environment running.
+Take a look at `Envfile`. This file lists all the `ENV` variables we use and provides a fake default for any missing keys. You'll need to get your own free [Algolia credentials][algolia] to get your development environment running.
 
-The [backend guide](/backend) will show you how to get free API keys for additional services that may be required to run certain parts of the app.
+The [backend guide][backend_guide] will show you how to get free API keys for additional services that may be required to run certain parts of the app.
 
-For any key that you wish to enter/replace:
+To set up keys for your local instance of DEV, you'll need to create an `application.yml` file. You can do this by copying the file called `sample_application.yml` in the `config` directory:
 
-1. Create `config/application.yml` by copying from the provided template (i.e. with bash: `cp config/sample_application.yml config/application.yml`). This is a personal file that is ignored in git.
-1. Obtain the development variable and apply the key you wish to enter/replace. i.e.:
+```shell
+cp config/sample_application.yml config/application.yml
+```
+
+Then, add each key you need to the `application.yml` file. For example, if you're setting up GitHub authentication:
 
 ```shell
 GITHUB_KEY: "SOME_REAL_SECURE_KEY_HERE"
 GITHUB_SECRET: "ANOTHER_REAL_SECURE_KEY_HERE"
 ```
 
-If you are missing `ENV` variables on bootup, the [envied](https://rubygems.org/gems/envied) gem will alert you with messages similar to `'error_on_missing_variables!': The following environment variables should be set: A_MISSING_KEY.`.
+(Don't worry, your `application.yml` file is ignored by git)
 
-You do not need "real" keys for basic development. Some features require certain keys, so you may be able to add them as you go.
+If you are missing `ENV` variables on bootup, the [envied][envied] gem will alert you with messages similar to `'error_on_missing_variables!': The following environment variables should be set: A_MISSING_KEY.`.
+
+Only certain features require "real" keys, so you may be able to add them as you work on different areas of the application.
+
+[algolia]: /backend/algolia
+[backend_guide]: /backend
+[envied]: https://rubygems.org/gems/envied

docs/getting-started/db.md

@@ -4,15 +4,18 @@ title: Preparing the Database
 
 # Preparing the database
 
-We need to create our database, load the database schema, and load seed
-data. This can be accomplished with:
+The next step is to create and prepare the database. Thankfully, DEV is a
+Rails application, so this is relatively easy.
+
+We can use Rails to create our database, load the schema, and add some seed
+data:
 
 ```shell
 rails db:setup
 ```
 
 `db:setup` actually runs the following rake commands in order so
-you could alternatively run each of these to produce the same result.
+alternatively, you could run each of these to produce the same result:
 
 ```shell
 rails db:create

docs/getting-started/forking.md

@@ -1,13 +1,28 @@
 ---
-title: Forking The Repo
+title: Forking the Repo
 ---
 
 # Forking the repository
 
-Fork DEV's repository: <https://github.com/thepracticaldev/dev.to/fork>
+The first step in contributing to any Open Source project on GitHub is
+[forking][forking] so that you can create
+[Pull Requests][pull_requests]. If you're not familiar with the idea of forking
+a repository, [GitHub has a super simple tutorial][forking_tutorial]!
 
-Clone your forked repository:
+If you're ready to get started, [fork DEV's repository][fork_dev]!
+
+Once you've got a fork on GitHub, you can clone your fork to run the project
+locally:
 
 ```shell
 git clone https://github.com/<your-username>/dev.to.git
 ```
+
+As time goes on, you may need to refresh your fork. If you have trouble with
+that, you can read about [keeping a fork caught up on DEV][refresh_your_fork]!
+
+[forking]: https://help.github.com/en/articles/fork-a-repo
+[fork_dev]: https://github.com/thepracticaldev/dev.to/fork
+[forking_tutorial]: https://guides.github.com/activities/forking/
+[pull_requests]: https://help.github.com/en/articles/about-pull-requests
+[refresh_your_fork]: https://dev.to/jacobherrington/a-fool-proof-way-to-keep-your-fork-caught-up-in-git-2e2e

docs/getting-started/start-app.md

@@ -2,17 +2,36 @@
 title: Starting the Application
 ---
 
-# Starting the Application
+# Starting the application
 
-We're mostly a Rails app, with a bit of Webpack sprinkled in. **For most cases, simply running `bin/rails server` will do.** If you're working with Webpack though, you'll need to run the following:
+We're a Rails app, and we use [Webpacker][webpacker] to manage some of
+our JavaScript.
 
-- Run **`bin/startup`** to start the server, Webpack, and our job runner `delayed_job`. `bin/startup` runs `foreman start -f Procfile.dev` under the hood.
-- `alias start="bin/startup"` makes this even faster. 😊
-- If you're using **`pry`** for debugging in Rails, note that using `foreman` and `pry` together works, but it's not as clean as `bin/rails server`.
+Start the application, Webpack, and our job runner [delayed_job][delayed_job]
+by running:
 
-Here are some singleton commands you may need, usually in a separate instance/tab of your shell.
+```shell
+bin/startup
+```
 
-- Running the job server (if using `bin/rails server`) -- this is mostly for notifications and emails: **`bin/rails jobs:work`**
-- Clearing jobs (in case you don't want to wait for the backlog of jobs): **`bin/rails jobs:clear`**
+(This just runs `foreman start -f Procfile.dev`)
 
-Current gotchas: potential environment issues with external services need to be worked out.
+If you're working on DEV regularly, you can use `alias start="bin/startup"` to
+make this even easier. 😊
+
+If you're using **`pry`** for debugging in Rails, note that using `foreman`
+and `pry` together works, but it's not as clean as `bin/rails server`.
+
+Here are some singleton commands you may need, usually in a separate
+instance/tab of your shell.
+
+- Running the job server (if using `bin/rails server`) -- this is mostly for
+notifications and emails: **`bin/rails jobs:work`**
+- Clearing jobs (in case you don't want to wait for the backlog of jobs):
+**`bin/rails jobs:clear`**
+
+Current gotchas: potential environment issues with external services need to be
+worked out.
+
+[delayed_job]: https://github.com/collectiveidea/delayed_job_active_record
+[webpacker]: https://github.com/rails/webpacker

docs/getting-started/workflow.md

@@ -2,7 +2,7 @@
 title: Suggested Workflow
 ---
 
-# Suggested Workflow
+# Suggested workflow
 
 We use [Spring](https://github.com/rails/spring), and it is already included in the project.