clean up readme and docs (#3660)

* clean up readme and docs

* add missing files

README.md

@@ -64,25 +64,11 @@ We encourage you to contribute to dev.to! Please check out the [Contributing to
 
 We run on a Rails backend with mostly vanilla JavaScript on the front end, and some Preact sprinkled in. One of our goals is to move to mostly Preact for our front end.
 
-Additional technologies and services are listed on [our docs](https://docs.dev.to).
-
-### Engineering standards
-
-#### 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
-
-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.
-
-Note: if you've already installed the [husky](https://github.com/typicode/husky) package at least once (used for precommit npm script), you will need to run `yarn --force` or `npm install --no-cache`. For some reason, the post-install script of husky does not run when the package is pulled from yarn or npm's cache. This is not husky specific, but rather a cached package issue.
+Additional technologies and services are listed on [our docs](https://docs.dev.to/technical-overview/).
 
 ## Getting Started
 
-This section provides a high-level requirement & quick start guide. For detailed installations, please check out our [docs](http://docs.dev.to/installation).
+This section provides a high-level requirement & quick start guide. **For detailed installations, such as getting started with GitPod, Docker, or specific operating systems, please check out our [docs](http://docs.dev.to).**
 
 ### Prerequisites
 
@@ -114,25 +100,6 @@ This section provides a high-level requirement & quick start guide. For detailed
 
 [View Full Installation Documentation](https://docs.dev.to/installation/)
 
-### Docker Installation (BETA)
-
-Our docker implementation is incomplete and may not work smoothly. Please kindly report any issues and any contribution is welcomed!
-
-1. Install `docker` and `docker-compose`
-1. `git clone git@github.com:thepracticaldev/dev.to.git`
-1. Set environment variables above as described in the ["Standard Installation"](#standard-installation)
-1. run `docker-compose build`
-1. run `docker-compose run web rails db:setup`
-1. run `docker-compose run web yarn install`
-1. run `docker-compose up`
-1. That's it! Navigate to `localhost:3000`
-
-### Gitpod Installation
-
-Simply open dev.to in Gitpod, a free online dev environment for GitHub:
-
-[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/thepracticaldev/dev.to)
-
 #### 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:

docs/getting-started/committing.md

@@ -4,6 +4,14 @@ title: Committing
 
 # Committing and Pre-Commit Hooks
 
+## 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
+
 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.
 
 Note: if you've already installed the [husky](https://github.com/typicode/husky) package at least once (used for precommit npm script), you will need to run `yarn --force` or `npm install --no-cache`. For some reason, the post-install script of husky does not run when the package is pulled from yarn or npm's cache. This is not husky specific, but rather a cached package issue.

docs/getting-started/readme.md

@@ -4,6 +4,8 @@ items:
   - forking.md
   - config-env.md
   - db.md
+  - start-app.md
+  - workflow.md
   - branching.md
   - committing.md
   - pull-request.md

docs/getting-started/start-app.md

@@ -0,0 +1,18 @@
+---
+title: 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:
+
+- 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`.
+
+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.

docs/getting-started/workflow.md

@@ -0,0 +1,13 @@
+---
+title: Suggested Workflow
+---
+
+# Suggested Workflow
+
+We use [Spring](https://github.com/rails/spring) and it is already included in the project.
+
+1.  Use the provided bin stubs to automatically start Spring, i.e. `bin/rails server`, `bin/rspec spec/models/`, `bin/rails db:migrate`.
+1.  If Spring isn't picking up on new changes, use `spring stop`. For example, Spring should always be restarted if there's a change in environment key.
+1.  Check Spring's status whenever with `spring status`.
+
+Caveat: `bin/rspec` is not equipped with Spring because it affects Simplecov's result. Instead use `bin/spring rspec`.

docs/installation/docker.md

@@ -1,5 +1,7 @@
 # Installing DEV with Docker [Beta]
 
+Our docker implementation is incomplete and may not work smoothly. Please kindly [report any issues](https://github.com/thepracticaldev/dev.to/issues/new/choose)!
+
 ## Installing prerequisites
 
 _These prerequisites assume you're working on an operating system supported by Docker._

docs/installation/gitpod.md

@@ -6,4 +6,6 @@ title: GitPod
 
 If you prefer working on a cloud IDE, you can spin up your own instance of DEV in the cloud, using [GitPod](https://gitpod.io/#https://github.com/thepracticaldev/dev.to).
 
+[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/thepracticaldev/dev.to)
+
 You can find more information about this, [in a DEV's article](https://dev.to/ben/spin-up-a-local-instance-of-dev-in-the-cloud-with-gitpod-it-s-incredibly-simple-pij).

docs/installation/readme.md

@@ -22,7 +22,7 @@ Installing to your local machine can be troublesome for many reasons such as a c
 
 Another way you can get a development environment up and running is with Docker. Docker will install everything you need in an isolated container, and you need not concern about the details. We have instructions for installing with [Docker](/installation/docker).
 
-## GitPod
+## GitPod _- beginner friendly!_
 
 If you are having trouble with local installation and Docker confuses you, then you can launch a **development environment** with the press of a button with GitPod.