Merge pull request #1741 from codetriage/schneems/add-book-to-university

Update university pages

Author: schneems

app/views/university/example_app.md.erb

@@ -1,19 +1,31 @@
 An example app is an application that is designed to reproduce a bug or demonstrate an issue.
 
-An example app is not a gigantic repo, your private source code, or telling someone a series of bash commands.
+**Q: "What is an example app?"**
 
-Before a bug can be fixed, it has to be understood and reproduced. For every issue, a maintainer gets, they have to decipher what was supposed to happen and then spend minutes or hours piecing together their reproduction.
+A way to reliably trigger a bug or demonstrate bad behavior in a contained, easily executable application. It is a specific form of [a reproduction](https://codetriage.com/reproduction).
 
-Usually, they can't get it right, so they have to ask for clarification. This back-and-forth process takes lots of energy and wastes everyone's time. Instead, it's better to provide an example app from the beginning.
+**Q: "What isn't an example app?"**
 
-At the end of the day, would you rather maintainers spend their time making example apps or fixing issues?
+An example app is not a step-by-step story of things you did to trigger the error, such as "I clicked this link" or "I entered this command" or "I compiled this code." While such descriptions can sometimes be helpful, they're often missing crucial contexts that might require guessing on the part of the person debugging. Chances are if your "reproduction" doesn't involve source control, it's not "a reproduction app."
+
+**Q: "Why should I make an example app?"**
+
+Before someone can fix a bug, they need to understand why it happens. While descriptions can help, the golden standard for debugging code is to be able to reproduce the bug. The easier it is to reproduce the bug, the shorter the debugging cycles will take, and the faster it can be fixed.
+
+**Q: "Does that mean I should send my whole application over when I open a bug report?"**
+
+Please no. Reproduction code is best when there's a minimal amount of code necessary to reproduce the issue. The more extra stuff there is, the harder it may be to separate what's causing the bug versus what's just there.
+
+**Q: "Is a series of shell commands in an issue description reproduction code?"**
+
+Instead of making a full-on reproduction committed to source control, it might be tempting to provide a bunch of shell commands instead. While a handful of shell commands is better than nothing, there's an extremely high chance that the person debugging won't be able to reproduce your issue. When this happens, they have to ask for clarification. This back-and-forth process takes lots of energy and wastes everyone's time. Instead, it's better to provide an executable reproduction from the beginning.
 
 ## How to make an example app
 
 1. Start with a clean app with no other features.
 2. Add whatever code is necessary to demonstrate the issue.
 3. Add instructions to the README describing how to boot the app and reproduce the problem.
-4. Push the example app somewhere public such as GitHub.
+4. Push the example app somewhere public, such as GitHub.
 5. Bonus: Give the app to a friend or co-worker. See if they can repro the problem without any instructions other than what's in the README.
 6. Finally: Give a link to the example app to a maintainer (usually through an issue).
 
@@ -37,9 +49,7 @@ Better yet, send them a link to this page to help them understand why and how to
 Please provide an [example app that can reproduce this issue](https://www.codetriage.com/example_app).
 </textarea>
 
-<center>
-  <img src="https://www.dropbox.com/s/woa4h08jwuobzgp/example-apps.gif?raw=1" />
-</center>
+For additional tips on creating and responding to issues, check out the [How to Open Source](https://howtoopensource.dev/) book.
 
 <% if !current_user %>
 
@@ -49,7 +59,6 @@ CodeTriage is the easiest way to get started contributing to open source.
 
 Sign up, subscribe to repos you want to help, and we send you contribution ideas in your inbox. Easy Peazy. If you want to know more read <a href="what">What is CodeTriage</a>.
 
-
 <br />
 <center>
   <%= link_to "Sign up via GitHub", user_github_omniauth_authorize_path, method: :post, class: 'button' %>

app/views/university/index.md.erb

@@ -7,6 +7,16 @@ While CodeTriage helps by sending issues from repos, how do you pick the open-so
 - **[Picking an open-source repo to help](university/picking_a_repo)**
 - **[Triage with Me - 11 issues & 2 PRs in 1.5 hours](https://www.schneems.com/2020/09/22/triage-with-me-11-issues-2-prs-in-15-hours/)**
 
+## The handbook
+
+- [How to Open Source](https://howtoopensource.dev) is a paid book by Richard Schneeman sold under a creative commons license. It aims to teach developers actionable steps to grow from a coder into a contributor.
+
+<div align="center">
+  <a href="https://howtoopensource.dev/">
+    <img src="https://howtoopensource.dev/images/HowToOpenSource_FinalCover.jpg" style="width: 150px" alt="How to Open Source book cover" />
+  </a>
+</div>
+
 ## I want to report a bug
 
 When opening an issue about a bug, the number one thing anyone will want to know is: "how can I reproduce this problem." To help answer that question we've got some guides helping to explain what an excellent reproduction looks like and why:
@@ -20,4 +30,3 @@ When you make a PR (Pull Request), the maintainer might ask you to do some house
 
 - **[Rebase your code](rebase)**
 - **[Squash your commits](squash)**
-

app/views/university/picking_a_repo.md.erb

@@ -57,3 +57,4 @@ Don't wait for the "perfect" contribution opportunity. Don't wait for the "perfe
 
 You can find [repos listed on the homepage](https://www.codetriage.com).
 
+For additional tips on finding contribution opportunities, check out the [How to Open Source](https://howtoopensource.dev) book.

app/views/university/reproduction_code.md.erb

@@ -1,19 +1,26 @@
 ## Please Provide Reproduction Code
 
-**What is Reproduction code?** A way to reliably trigger a bug or demonstrate bad behavior in a contained, easily executable package.
+**Q: "What is Reproduction code?"**
 
-**What isn't Reproduction code?** Repro code is not a step-by-step story of things you did to trigger the error, such as "I clicked this link" or "I entered this command" or "I compiled this code." While such descriptions can sometimes be helpful, they're often missing crucial contexts that might require guessing on the part of the person debugging. Chances are if your "reproduction" doesn't involve source control, it's not "reproduction code."
+A way to reliably trigger a bug or demonstrate bad behavior in a contained, easily executable package.
 
-**Why should I make a Reproduction?** Before someone can fix a bug, they need to understand why it happens. While descriptions can help, the golden standard for debugging code is to be able to reproduce the bug. The easier it is to reproduce the bug, the shorter the debugging cycles will take, and the faster it can be fixed.
+A specialized case of "reproduction code" is an [example app](https://www.codetriage.com/example_app) if you're the open-source library is a framework for application development.
 
-- An example could be: Creating a new "clean" repository on GitHub that includes all code, declares dependencies, and instructions necessary to see the behavior.
-- An example could be: Adding a failing test added to the repo
+**Q: "What isn't Reproduction code?"**
 
-A specialized case of "reproduction code" is an [example app](https://www.codetriage.com/example_app) if you're the open-source library is a framework for application development.
+Repro code is not a step-by-step story of things you did to trigger the error, such as "I clicked this link" or "I entered this command" or "I compiled this code." While such descriptions can sometimes be helpful, they're often missing crucial contexts that might require guessing on the part of the person debugging. Chances are if your "reproduction" doesn't involve source control, it's not "reproduction code."
+
+**Q: "Why should I make a Reproduction?"**
+
+Before someone can fix a bug, they need to understand why it happens. While descriptions can help, the golden standard for debugging code is to be able to reproduce the bug. The easier it is to reproduce the bug, the shorter the debugging cycles will take, and the faster it can be fixed.
+
+**Q: "Does that mean I should send my whole application over when I open a bug report?"**
 
-**Does that mean I should send my whole application over when I open a bug report?** Please no. Reproduction code is best when there's a minimal amount of code necessary to reproduce the issue. The more extra stuff there is, the harder it may be to separate what's causing the bug versus what's just there.
+Please no. Reproduction code is best when there's a minimal amount of code necessary to reproduce the issue. The more extra stuff there is, the harder it may be to separate what's causing the bug versus what's just there.
 
-**Is a series of shell commands in an issue description reproduction code?** Instead of making a full-on reproduction committed to source control, it might be tempting to provide a bunch of shell commands instead. While a handful of shell commands is better than nothing,  there's an extremely high chance that the person debugging won't be able to reproduce your issue. When this happens, they have to ask for clarification. This back-and-forth process takes lots of energy and wastes everyone's time. Instead, it's better to provide an executable reproduction from the beginning.
+**Q: "Is a series of shell commands in an issue description reproduction code?"**
+
+Instead of making a full-on reproduction committed to source control, it might be tempting to provide a bunch of shell commands instead. While a handful of shell commands is better than nothing,  there's an extremely high chance that the person debugging won't be able to reproduce your issue. When this happens, they have to ask for clarification. This back-and-forth process takes lots of energy and wastes everyone's time. Instead, it's better to provide an executable reproduction from the beginning.
 
 ## How to make reproduction code
 
@@ -40,6 +47,12 @@ If you see an open bug report that does not have a working reproduction ask them
 
 Better yet, send them a link to this page to help them understand why and how to make one!
 
+<textarea>
+Please provide a [working reproduction](https://www.codetriage.com/reproduction).
+</textarea>
+
+For additional tips on creating and responding to issues, check out the [How to Open Source](https://howtoopensource.dev) book.
+
 <% if !current_user %>
 
 ## What is CodeTriage?
@@ -48,7 +61,6 @@ CodeTriage is the easiest way to get started contributing to open source.
 
 Sign up, subscribe to repos you want to help, and we send you contribution ideas in your inbox. Easy Peazy. If you want to know more read <a href="what">What is CodeTriage</a>.
 
-
 <br />
 <center>
   <%= link_to "Sign up via GitHub", user_github_omniauth_authorize_path, method: :post, class: 'button' %>