docs: missing workflows

docs/getting-started/rulesets.md

@@ -40,6 +40,41 @@ While running it with this object, it will succeed:
 }
 ```
 
+### Severity
+
+The `severity` keyword is optional and can be `error`, `warn`, `info`, or `hint`.
+
+### Then
+
+The Then part of the rules explains what to do with the `given` JSON Path, and involves two required keywords:
+
+```yaml
+  then:
+    field: description
+    function: truthy
+```
+
+The `field` keyword is just the name for a property in the object just selected. It could also be `@key` if the given path is an object.
+
+```yaml
+given: '$.responses'
+then:
+  field: '@key'
+  function: pattern
+  functionOptions:
+    match: '^[0-9]+$' 
+```
+
+The above pattern based rule would error on `456avbas` as it is not numeric.
+
+```yaml
+responses:
+  123:
+    foo: bar
+  456avbas:
+    foo: bar
+```
+
 ### Extending Rules
 
 Rulesets can extend other rulesets. For example, Spectral comes with two built in rulesets - one for OpenAPI v2 (`spectral:oas2`), and one for OpenAPI v3 (`spectral:oas3`). 
@@ -93,7 +128,7 @@ The current recommended rules are marked with the property `recommended: true` i
 - [Rules specific to only OpenAPI v2](https://github.com/stoplightio/spectral/tree/develop/src/rulesets/oas2/index.json)
 - [Rules specific to only OpenAPI v3](https://github.com/stoplightio/spectral/tree/develop/src/rulesets/oas3/index.json)
 
-### Changing Severity of a rule
+### Changing Severity of a Rule
 
 ```yaml
 extends: spectral:oas2

docs/guides/workflows.md

@@ -0,0 +1,65 @@
+# Workflow
+
+When and where should you use Spectral? 
+
+It depends a lot how you are creating and managing your API description documents, but probably wherever they are being made. [Stoplight Studio](https://stoplight.io/spectral/) users have Spectral baked right into the editor, but if you are using another text-editor or IDE you can switch to the command-line and run Spectral [as a CLI tool][cli].
+
+## Linting Design-First Workflows
+
+If the developer is just in the early stages of planning and designing the API, they could run Spectral against their design docs and get feedback very early on. If they are using Studio, Spectral will be running automatically as they work, without the developer even needing to switch to the CLI.
+
+Seeing these errors and warnings will help nudge the developer towards creating consistent APIs, quickly and easily, without needing to have "OpenAPI Gatekeepers" to enforce the rules manually. Those folks are not infallible, they can miss things, but Spectral can be used to free those people up for bigger and better things.
+
+## Linting Code-First Workflows
+
+Using Spectral gets a little tricky for developers who are following a code-first (a.k.a "design-second") workflow. If the API description documents live in YAML or JSON files then its fine, and the design-first workflow can be used: with new changes being linted. 
+
+If the API description documents live in some other format, maybe as comments or annotations inside code, Spectral has no way to read that. Hopefully that annotations-based tool has some sort of export option on the CLI. Here's an example for those using [go-swagger](https://github.com/go-swagger/go-swagger).
+
+```bash
+swagger generate spec -o ./tmp/openapi.json && spectral lint ./tmp/openapi.json
+```
+
+Sadly by the time you've already written your code, if Spectral points anything out related to your actual API, and not providing feedback on the API description document itself, figuring out what to do next might be troublesome. 
+
+For example if the API has a bunch of URLs with underscores, then becoming consistent is either a case of waiting for the next major version and changing things in there, or taking a more evolution-based approach, aliasing `/example_url` to `/example-url`, then look into [deprecating the old URL](https://apisyouwonthate.com/blog/api-evolution-for-rest-http-apis/).
+
+## Git-hooks
+
+Folks will forget to run Spectral, and that means they can commit broken or (low quality) documents. Adding a git commit hook can be a simple solution to this using something like [Husky](https://github.com/typicode/husky).
+
+```
+// package.json
+{
+  "husky": {
+    "hooks": {
+      "pre-commit": "spectral lint openapi.yaml",
+      "pre-push": "spectral lint openapi.yaml",
+      "...": "..."
+    }
+  }
+}
+```
+
+See our [CLI documentation][cli] to see what other arguments and options can be used.
+
+## Continuous Integration
+
+Running Spectral on CI servers is just a case of doing what you'd do in the CI.
+
+``` yaml
+version: 2
+jobs:
+  build:
+    docker:
+      - image: circleci/node:12
+    steps:
+      - checkout
+      - run:
+          name: "API Description Linter"
+          command: npx @stoplight/spectral lint somefile.yaml -- --ruleset=config/custom-ruleset.yaml
+```
+
+We plan to add JUnit/xUnit test results in a future version, so tools like CircleCI can show test results in a more visual way. For now, the commands exit code will alert CI that there was a problem, and the console output will say why.
+
+[cli]: https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/guides/cli.md

docs/reference/functions.md

@@ -1,7 +1,8 @@
 # Core Functions
 
-Rules use "functions and those can be custom defined. To save everyone the effort of writing functions for common tasks, Spectral comes with a few bundled out of the box. 
+Rules use "functions" and those can be custom defined. To save everyone the effort of writing functions for common tasks, Spectral comes with a few bundled out of the box. 
 
+All functions 
 
 ## alphabetical
 
@@ -14,7 +15,6 @@ Enforce alphabetical content, for simple arrays, or for objects by passing a key
 ``` yaml
   openapi-tags-alphabetical:
     description: OpenAPI object should have alphabetical `tags`.
-    recommended: false
     type: style
     given: "$"
     then: