Clearer docs overall (from examples to tone)

duckduckhack/getting-started/contributing.md

@@ -1,12 +1,16 @@
 # How Can I Contribute?
 
-There are several options for contributing to DuckDuckHack, explained below. If you have any questions at any point, feel free to ask on one of our community channels:
+Contributing to DuckDuckHack - at any level - by nature makes a huge impact. 
+
+## Reach Out
+
+If you have any questions at any point, feel free to ask on one of our community channels:
 
 - [Request invite to our Slack team](mailto:[email protected]?subject=AddMe)
 - [DuckDuckHack mailing list](https://duck.co/redir/?u=https%3A%2F%2Fwww.listbox.com%2Fsubscribe%2F%3Flist_id%3D197814)
 - Do not hesitate to email us directly at [[email protected]](mailto:[email protected]).
 
-## New? Make Your First Contribution Today
+## New? Get Your First Taste Today
 
 If this is your first time contributing to [DuckDuckHack](http://www.duckduckhack.com), you have two great ways to quickly make your first commit:
 
@@ -18,9 +22,9 @@ Cheat sheets are a super-easy way to contribute to the live DuckDuckGo AnswerBar
 
 This short tutorial will lead you through all the parts of building a full-loop Goodie. This is a perfect place to start if you have an idea for an original Instant Answer.
 
-## Create a New Instant Answer
+## Feeling Good? Create a New Instant Answer
 
-Once you're comfortable with the workflow and how Goodies work, we're excited to have you create your own original Instant Answer:
+Once you're comfortable with the workflow and how Goodies work, we're excited to have you create your own original Instant Answer. 
 
 **1. Choose an idea**
 
@@ -62,7 +66,9 @@ Thanks!
 PS: DuckDuckGo is awesome!
 ```
 
-## Improve an Existing Instant Answer
+P.S. To see just how simple it is to contribute an Instant Answer, check out David Farrell's PerlTricks post: [Writing Instant Answers is Easy](http://perltricks.com/article/169/2015/4/20/Writing-DuckDuckGo-instant-answers-is-easy).
+
+## Share Your Wisdom: Improve an Existing Instant Answer
 
 Another great way to contribute is to improve an existing, live Instant Answer. It's a great way to get further acquainted with Instant Answers, as well as get implementation ideas. (Many contributors report completing their first fix within two hours of forking the repository!)
 

duckduckhack/getting-started/ddh-intro.md

@@ -1,24 +1,53 @@
-# Welcome to DuckDuckHack!
+# Welcome to DuckDuckHack
 
-We are a community of DuckDuckGo users who help improve the search engine with, "Instant Answers". To get started, please [request an invite to our Slack team](mailto:[email protected]?subject=AddMe). You may join multiple Slack channels to discuss your Instant Answer ideas with others who may have the same interests! 
+We are a community of DuckDuckGo users who invent and maintain "Instant Answers".
 
-- [Request Slack invite](mailto:[email protected]?subject=AddMe)
+*Find out [how to contribute](https://duck.co/duckduckhack/contributing), how to [contact us](https://duck.co/duckduckhack/contributing#reach-out) and get involved.*
 
-You may also wish to join our DuckDuckHack Dev's email list (low traffic):
+## What are Instant Answers?
 
-- [DuckDuckHack developer mailing list](https://www.listbox.com/subscribe/?list_id=197814)
+**Instant Answers present what you were seeking in zero clicks:**
 
+![](https://images.duckduckgo.com/iu/?u=https%3A%2F%2Fraw.githubusercontent.com%2Fduckduckgo%2Fduckduckgo-documentation%2Fmaster%2Fduckduckhack%2Fassets%2Falternative_spotify.png)
 
-## What are Instant Answers?
+Instant Answers go right at the top of DuckDuckGo's search results - above ads and even search results. They have the potential to show up on millions of searches every day. 
 
-Instant Answers help you find what you're looking for in few or zero clicks. They're placed above ads and regular search results, and they're created/maintained by you (the community). Some Instant Answers are built from pure code and others require external sources (API requests), databases, or key-value stores. The possibilities are endless but the point is to provide a perfect result for every search. 
+Our mission as a community is to cover every topic with an Instant Answer. We're well on our way: you can browse the [full list of Instant Answers](https://duck.co/ia) and see what's been contributed.
 
-![App search Instant Answer example](https://images.duckduckgo.com/iu/?u=https%3A%2F%2Fraw.githubusercontent.com%2Fduckduckgo%2Fduckduckgo-documentation%2Fmaster%2Fduckduckhack%2Fassets%2Fapp_search_example.png&f=1)
+They can be really complicated and dynamic...
+
+![](https://images.duckduckgo.com/iu/?u=https%3A%2F%2Fraw.githubusercontent.com%2Fduckduckgo%2Fduckduckgo-documentation%2Fmaster%2Fduckduckhack%2Fassets%2Fparking_ny.png)
+
+...or super simple yet convenient.
+
+![](https://images.duckduckgo.com/iu/?u=https%3A%2F%2Fraw.githubusercontent.com%2Fduckduckgo%2Fduckduckgo-documentation%2Fmaster%2Fduckduckhack%2Fassets%2Fsales_tax.png)
+
+Some are just cool: 
+
+![](https://images.duckduckgo.com/iu/?u=https%3A%2F%2Fraw.githubusercontent.com%2Fduckduckgo%2Fduckduckgo-documentation%2Fmaster%2Fduckduckhack%2Fassets%2Fheads_tails.png)
+
+Many are absolutely delightful and unexpected:
 
-In the above example, [Quixey](http://quixey.com/) was a source that our own DuckDuckHack Community suggested for mobile app search. Now, any time someone searches for apps on DuckDuckGo, we request information directly from Quixey to help answer the search. 
+![](https://images.duckduckgo.com/iu/?u=https%3A%2F%2Fraw.githubusercontent.com%2Fduckduckgo%2Fduckduckgo-documentation%2Fmaster%2Fduckduckhack%2Fassets%2Fbpm_ms.png)
+
+Many are super practical...
+
+![](https://images.duckduckgo.com/iu/?u=https%3A%2F%2Fraw.githubusercontent.com%2Fduckduckgo%2Fduckduckgo-documentation%2Fmaster%2Fduckduckhack%2Fassets%2Fair_quality.png)
+
+...in ways we never imagined:
+
+![](https://images.duckduckgo.com/iu/?u=https%3A%2F%2Fraw.githubusercontent.com%2Fduckduckgo%2Fduckduckgo-documentation%2Fmaster%2Fduckduckhack%2Fassets%2Fblue_pill.png)
+
+Some Instant Answers are built from pure code:
+
+![](https://images.duckduckgo.com/iu/?u=https%3A%2F%2Fraw.githubusercontent.com%2Fduckduckgo%2Fduckduckgo-documentation%2Fmaster%2Fduckduckhack%2Fassets%2Furl_encode.png)
+
+Other Instant Answers channel external sources (API requests), databases, or key-value stores. 
+
+![App search Instant Answer example](https://images.duckduckgo.com/iu/?u=https%3A%2F%2Fraw.githubusercontent.com%2Fduckduckgo%2Fduckduckgo-documentation%2Fmaster%2Fduckduckhack%2Fassets%2Fapp_search_example.png&f=1)
 
-To see just how simple it is to contribute an Instant Answer, check out David Farrell's PerlTricks post: [Writing Instant Answers is Easy](http://perltricks.com/article/169/2015/4/20/Writing-DuckDuckGo-instant-answers-is-easy).
+**The [possibilities are endless](https://duck.co/ideas) but the point is to provide a perfect result for every search.**
 
-In these docs, we'll show you how to build Instant Answers that can do this and more. Start by reading about [ways to contribute](https://duck.co/duckduckhack/contributing).
+In these docs, we'll show you how to build Instant Answers that can do this and more. Let's get started with [ways to contribute](https://duck.co/duckduckhack/contributing).
 
 

duckduckhack/getting-started/setup_dev_environment.md

@@ -6,30 +6,29 @@ Before moving forward, you **must** know which Instant Answer type you will be u
 
 ## Before you start...
 
-We highly recommend that everyone uses Codio, a web-based IDE that simplifies the setup and development process greatly. If you prefer using a local text editor, that's alright, but using Codio is still beneficial because we already have the required software installed and ready to go. This page will show you how to set up Codio and then it's on to creating Instant Answers! You can also watch a [video screencast of this tutorial](https://vimeo.com/132712266).
+We highly recommend that everyone uses Codio, a web-based IDE that simplifies the setup and development process greatly. Codio is beneficial because we already have the required software installed and ready to go. 
 
-### Alternative Development Environments 
+This page will show you how to set up Codio and then it's on to creating Instant Answers! You can also watch a [video screencast of this tutorial](https://vimeo.com/132712266).
 
-Codio is the preferred choice of most DuckDuckHack contributors for its ease and speed. However, you may also [develop and test locally](https://duck.co/duckduckhack/other_development_environments), or install a [pre-configured virtual machine](https://duck.co/duckduckhack/other_development_environments). These options do require more time and effort than using Codio.
+For those who prefer local development, there are more involved options to [develop and test locally](https://duck.co/duckduckhack/other_development_environments), or install a [pre-configured virtual machine](https://duck.co/duckduckhack/other_development_environments). These options require significantly more time and effort than using Codio.
 
 ## Sign up for a GitHub Account
 
 *Already have a GitHub Account? Perfect, move on to [the next step](#sign-up-for-a-codio-account)!*
 
-If you're new to programming, GitHub is a well known, popular tool that many individuals and companies use to save their code. Many open-source projects (such as DuckDuckHack) are hosted on GitHub and anyone with an account can contribute. GitHub is a great tool that you will likely be using long after this tutorial. To get started, let's sign up!
+If you're new to programming, GitHub is a well known, popular tool that many individuals and companies use to save their code. Many open-source projects (such as DuckDuckHack) are hosted on GitHub. The only requirement to contribute is an account - which is free! GitHub is a great tool that you will likely be using long after this tutorial. To get started, let's sign up!
 
 1. Go to https://github.com/join and enter the required information, then click "**Create an Account**"
 2. Click "**Finish Signup**" to continue with a **Free** GitHub account.
 
 **Congrats!** You now have a GitHub account.
 
-
 ## Sign up for a Codio Account
 
-Next, you'll need to get an account for Codio:
-
 *Already have a Codio Account? Perfect, move on to [the next step](#fork-the-duckduckhack-project-on-codio)!*
 
+Next, you'll need to get an account for Codio. Codio allows contributors to spawn identical development environments, allowing us to focus on the fun parts, rather than installing tools.
+
 1. Go to https://codio.com and click "**Get Started**", at the top right corner.
 2. Click "**Sign Up via GitHub**".
 3. If you aren't already signed into GitHub, enter your GitHub login details and then click "**Sign In**".
@@ -38,7 +37,7 @@ Next, you'll need to get an account for Codio:
 
 **Congrats!** You now have a Codio account. You'll notice that you didn't need to provide a password, that's because you've logged in to Codio using your GitHub account. As long as you can login to your GitHub account, you can also login to Codio. Now let's get started with setting up your Codio environment!
 
-## Join the DuckDuckGo Organization
+## Join the DuckDuckGo Codio Organization
 
 1. **After logging into Codio,** [click this link](https://codio.com/p/signup?orgToken=Ax-OB3tU4sdNAG8axJBYcjNqR04) and you'll be added to our organization, which gives you a professional Codio setup free of charge. You should see a confirmation message at the bottom of your Codio screen after clicking. 
 

duckduckhack/goodie/goodie_cheat_sheets.md

@@ -4,7 +4,21 @@ A popular (and perfect) use of Goodies is to create cheat sheets which are avail
 
 ![tmux cheat sheet](https://images.duckduckgo.com/iu/?u=https%3A%2F%2Fraw.githubusercontent.com%2Fduckduckgo%2Fduckduckgo-documentation%2Fmaster%2Fduckduckhack%2Fassets%2Ftmux_cheat_sheet.png&f=1)
 
-Looking for ideas for your cheat sheet? Check our [inspiration list](#cheat-sheet-ideas) below.
+Looking for ideas for your cheat sheet? Check out the wide variety of [existing cheat sheets](https://duck.co/ia?q=cheat+sheet) to get a taste. You can also take a look at our [inspiration list](#cheat-sheet-ideas) below. 
+
+## Cheat Sheet Ideas
+
+Keyboard shortcuts, video game cheat codes, meanings, and other reference information are wonderfully useful as a cheat sheet. Get inspired by [seeing what other contributors have done](https://duck.co/ia?q=cheat+sheet) with cheat sheets. Here are some other cheat sheet Instant Answers we love: 
+
+- [Regex help](https://duckduckgo.com/?q=regex+help&ia=cheatsheet)    
+- [Anniversary meanings](https://duckduckgo.com/?q=anniversary+help&ia=cheatsheet)  
+- [Cryptography terms and help](https://duckduckgo.com/?q=cryptography+cheat+sheet&ia=cheatsheet)  
+- [Harry Potter spells](https://duckduckgo.com/?q=harry+potter+spells+cheat+sheet&ia=cheatsheet)  
+- [Tennis info](https://duckduckgo.com/?q=tennis+cheat+sheet&ia=cheatsheet)  
+
+You can also [search our ideas forum for cheat sheets](https://duck.co/ideas/search?q=cheat+sheet), or [submit one of your own](https://duck.co/ideas/newidea)! 
+
+Of course, a cheat sheet is not always the best representation for your data. Sometimes, an Instant Answer is better built as a full [Goodie](https://duck.co/duckduckhack/goodie_overview) or another type of Instant Answer. When thinking about your idea, think about what would be most useful to a searcher.
 
 ## How to Add Your Cheat Sheet
 
@@ -216,15 +230,3 @@ We recommend displaying alternatives as follows:
 We've found the best way to express arrow keys is directly using arrow ASCII characters (←, ↑, →, ↓). Feel free to copy and paste the characters from here.
 
 For example, instead of **[Shift] [Up]** we recommend **[Shift] [↑]**.
-
-## Cheat Sheet Ideas
-
-A cheat sheet is not always the best representation for your data. Sometimes, an Instant Answer is better built as a full Goodie or another type of Instant Answer. When thinking about your cheat sheet idea, think about what is useful to a searcher. Keyboard shortcuts, video game cheat codes, and similar data can be wonderfully useful as a cheat sheet. Here are some other cheat sheet Instant Answers we love: 
-
-[Regex help](https://duckduckgo.com/?q=regex+help&ia=cheatsheet)    
-[Anniversary meanings](https://duckduckgo.com/?q=anniversary+help&ia=cheatsheet)  
-[Cryptography terms and help](https://duckduckgo.com/?q=cryptography+cheat+sheet&ia=cheatsheet)  
-[Harry Potter spells](https://duckduckgo.com/?q=harry+potter+spells+cheat+sheet&ia=cheatsheet)  
-[Tennis info](https://duckduckgo.com/?q=tennis+cheat+sheet&ia=cheatsheet)  
-
-You can also [search our ideas forum for cheat sheets](https://duck.co/ideas/search?q=cheat+sheet), or [submit one of your own](https://duck.co/ideas/newidea)! 

duckduckhack/goodie/goodie_displaying.md

@@ -2,6 +2,8 @@
 
 The final step of providing your Goodie results is displaying them in the DuckDuckGo AnswerBar.
 
+![goodieanswerbar](https://images.duckduckgo.com/iu/?u=https%3A%2F%2Fraw.githubusercontent.com%2Fduckduckgo%2Fduckduckgo-documentation%2Fmaster%2Fduckduckhack%2Fassets%2Fdiagrams%2Fgoodie_answerbar.png&f=1)
+
 ## Setting Display Properties in a Goodie
 
 Goodies are displayed according to a set of properties which can (mostly) be defined in each Goodie's Perl file. These options are returned as a hash called `structured_answer` when the Perl file finishes running. This hash is returned alongside the `$plaintext` string version of your Goodie result, used for the API):