Merge pull request #231 from danger/docs_lint

Improve the docs #trivial
danger · Apr 22, 2017 · 78c8498 · 78c8498
2 parents fe8f448 + 6aba0e4
commit 78c8498
Show file tree

Hide file tree

Showing 9 changed files with 44 additions and 28 deletions.
diff --git a/docs/guides/culture.html.md b/docs/guides/culture.html.md
@@ -1,19 +1,19 @@
 ---
 title: Cultural Changes
-subtitle: Plugin creation
-layout: guide
-order: 0
+subtitle: Cultural Changes
+layout: guide_js
+order: 2
 ---
 
-### Introducing Danger
+## Introducing Danger
 
 It can be easy to try and jump straight from no Dangerfile to a 200 line complex set of cultural rules. We'd advise against introducing a long list of rules for Danger all at once. In our experience, gradual integration works better. The entire team may have agreed on the changes, but slower adoption has worked better for teams new to working with Danger.
 
 At Artsy we've found that first just integrating Danger with a single simple rule (like checking for a CHANGELOG entry) then starting to introduce them piece-meal from different contributors has made it easier to go from "Ah, we shouldn't do that again" to "Oh, we could make a Danger rule for that" to "Here's the PR". 
 
 That is your end goal, making it so that everyone feels like it's easy to add and amend the rules as a project evolves. Making dramatic changes erodes that feeling, making regular small ones improves it.
 
-### Phrasing
+## Phrasing
 
 One of Danger's greatest features is that it can free individuals up on the team to stop being "the person who always requests more tests" on a PR. By moving a lot of the rote tasks in code review to a machine, you free up some mental space to concentrate on more important things. One of the downsides is that it is impossible to provide the same level of nuance in how you provide feedback.
 

diff --git a/docs/guides/faq.html.md b/docs/guides/faq.html.md
@@ -1,19 +1,19 @@
 ---
 title: FAQ
-subtitle: Plugin creation
-layout: guide
-order: 0
+subtitle: Frequently Asked Questions
+layout: guide_js
+order: 3
 ---
 
-### Can Danger comment inside a file on an PR?
+## Can Danger comment inside a file on an PR?
 
 Not yet, but there is a lot of discussion on [danger-js#77][77].
 
-### Can I use the same Dangerfile across many repos?
+## Can I use the same Dangerfile across many repos?
 
 Ish, it's currently quite complex to set up, but work is on-going on [Danger/Peril][peril]. This is a hosted version of Danger which does not need to run on CI. Using Peril you can use Dangerfiles to reply to basically any github webhook type.
 
-### I want to help influence Danger's direction
+## I want to help influence Danger's direction
 
 We'd recommend first becoming acquainted with the [VISION.md][] inside Danger, this is the long-term plan. Then there are two ways to start contributing today:
 

diff --git a/docs/guides/getting_started.html.md b/docs/guides/getting_started.html.md
@@ -1,6 +1,6 @@
 ---
 title: Getting Started with Danger JS
-subtitle: Plugin creation
+subtitle: Getting Started with Danger JS
 layout: guide_js
 order: 0
 ---
@@ -102,8 +102,24 @@ Danger is built to run as a part of this process, so you will need to have this
 
 You should be able to verify that you have successfully integrated Danger by either re-building your CI or pushing your new commits.
 
+## What now?
+
+There are a few of places you can go from here. We'd recommending opening tabs on all these articles:
+
+* [The Dangerfile][dangerfile].
+* [Cultural Changes of Danger][culture].
+* [The Dangerfile API reference][api].
+
+Then depending on the type of project you are working on, checking out either [Danger + Node App][app], or [Danger + Node Library][lib]. These should give you good overview of what is possible from here, then it's really up to you to find how you can codify some aspects of your team's culture.
+
+Good luck!
 
 [jest-config]: https://facebook.github.io/jest/docs/configuration.html
 [github_bots]: https://twitter.com/sebastiangrail/status/750844399563608065
 [github_token]: https://github.com/settings/tokens/new
 [Yarn]: https://yarnpkg.com
+[api]: /js/reference.html
+[dangerfile]: /js/guides/the_dangerfile.html
+[culture]: /js/guides/culture.html
+[app]: /js/tutorials/node-app.html
+[lib]: /js/tutorials/node-library.html
diff --git a/docs/guides/the_dangerfile.html.md b/docs/guides/the_dangerfile.html.md
@@ -1,6 +1,6 @@
 ---
 title: About the Dangerfile
-subtitle: Plugin creation
+subtitle: The Dangerfile
 layout: guide_js
 order: 1
 ---

diff --git a/docs/guides/troubleshooting.html.md b/docs/guides/troubleshooting.html.md
@@ -1,11 +1,11 @@
 ---
 title: Troubleshooting
-subtitle: Plugin creation
-layout: guide
-order: 0
+subtitle: Troubleshooting
+layout: guide_js
+order: 4
 ---
 
-### I only want to run Danger for internal contributors
+## I only want to run Danger for internal contributors
 
 Let's say you run Danger on the same CI service that deploys your code. If that's open source, you don't want to be letting anyone pull out your private env vars. The work around for this is to not simply call Danger on every test run:
 
@@ -15,7 +15,7 @@ Let's say you run Danger on the same CI service that deploys your code. If that'
 
 This ensures that Danger only runs when you have the environment variables set up to run. This is how Danger works for a lot of the mobile projects work in Artsy.
 
-### I'm seeing a lot of Cannot read property 'bind' in my tests
+## I'm seeing a lot of Cannot read property 'bind' in my tests
 
 This causes all of your tests to fail.
 

diff --git a/docs/tutorials/dependencies.html.md b/docs/tutorials/dependencies.html.md
@@ -1,8 +1,8 @@
 ---
 title: Danger + Dependencies
-subtitle: Plugin creation
+subtitle: Danger + Dependencies
 layout: guide_js
-order: 0
+order: 2
 ---
 
 ## Before we get started
@@ -41,7 +41,7 @@ There are two aspects that you consider:
 * Keeping track of changes to `dependencies` (for noted dependencies)
 * Reading the lockfile for the dependency (for transitive dependencies)
 
-### Keeping track of changes to `dependencies`
+### Keeping track of changes to dependencies
 
 We can use `danger.git.JSONDiffForFile` to understand the changes to a JSON file during code review. Note: it returns a promise, so we'll need to use `schedule` to make sure it runs async code correctly.
 

diff --git a/docs/tutorials/node-app.html.md b/docs/tutorials/node-app.html.md
@@ -1,6 +1,6 @@
 ---
 title: Danger in a Node App
-subtitle: Plugin creation
+subtitle: Danger + Node
 layout: guide_js
 order: 0
 ---
@@ -11,7 +11,7 @@ This guide continues after "[Getting Started][started]" - so you should have see
 
 ## "Node App"
 
-A node app could cover anything from an API, to a website, a native app or a hardware project. The rules on these projects tend to come from your larger dev team culture. In [Artsy][]] a lot of our rules for applications come from trying to have a similar culture between all projects.
+A node app could cover anything from an API, to a website, a native app or a hardware project. The rules on these projects tend to come from your larger dev team culture. In [Artsy][] a lot of our rules for applications come from trying to have a similar culture between all projects.
 
 ## Assignees
 

diff --git a/docs/tutorials/node-library.html.md b/docs/tutorials/node-library.html.md
@@ -1,8 +1,8 @@
 ---
 title: Danger + Node Library
-subtitle: Plugin creation
+subtitle: Danger + Node Library
 layout: guide_js
-order: 0
+order: 1
 ---
 
 ## Before we get started

diff --git a/docs/tutorials/typescript.html.md b/docs/tutorials/typescript.html.md
@@ -1,8 +1,8 @@
 ---
-title: TypeScript + Danger JS
-subtitle: Plugin creation
+title: Danger + TypeScript
+subtitle: Danger + TypeScript
 layout: guide_js
-order: 0
+order: 3
 ---
 
 ### TypeScript