Merge pull request #207 from rkdarst/conclusions

More in conclusions/recommendations, instructor guide

content/conclusions.md

@@ -1,11 +1,37 @@
 # Conclusions and recommendations
 
-- Explore and use the good tools that exist out there
-- An incomplete list of testing frameworks can be found in the [Quick Reference](quick-reference)
-- Automate tests: faster feedback and reduce the number of surprises
+## The basics
+- Learn one test framework well enough for basics
+  - Explore and use the good tools that exist out there
+  - An incomplete list of testing frameworks can be found in the [Quick Reference](quick-reference)
+- Start with some basics
+  - Some simple thing that test all parts
+- Automate tests
+  - Faster feedback and reduce the number of surprises
+
+## Going more in-depth
+
 - Strike a healthy balance between unit tests and integration tests
+- As the code gets larger and the chance of undetected bugs
+  increases, tests should increase.
 - When adding new functionality, also add tests
 - When you discover and fix a bug, also commit a test against this bug
 - Use code coverage analysis to identify untested or unused code
 - If you make your code easier to test, it becomes more modular
 
+
+## Ways to get started
+
+You probably won't do everything perfectly when you start off... But
+what are some of the easy starting points?
+
+- Do you have some single functions that are easy to test, but hard to
+  verify just by looking at them?  Add unit tests.
+
+- Do you have data analysis or simulation of some sort?  Make an
+  end-to-end test with sample data, or sample parameters.  This is
+  useful as an example anyway.
+
+- A local testing framework + Github actions is very easy!  And works
+  well in the background - you do whatever you want and get an email
+  if you break things.  It's actually pretty freeing.

content/guide.md

@@ -50,20 +50,22 @@ does not constitute science, and this can be offending to learners.
 
 ### Structure of the lesson
 
-#### Concepts
+#### Motivation and concepts
 
-After the Motivation episode, the lesson continues with a walkthrough
-of important concepts in software testing (unit tests, integration
-tests, test-driven development etc). At the end of the Concepts episode
-there's a link to the Quick Reference where learners can find a list of
-available testing frameworks for different languages.
+The former "motivation" and "concepts" episodes have been combined
+into one.  Previously, the lesson was described as quite dogmagtic and
+without enough time for exercises.  When teaching, try to give some of
+the benefits, but without being too long about it.  The quick
+reference has more details on language-specific things.
 
 #### Testing locally
 
 After introducing the concepts the lesson becomes hands-on in the
 Testing Locally episode. The pytest example there can be done as
 type-along and the optional exercise "Testing with numerical
-tolerance" can be left as homework.
+tolerance" can be left as homework.  The end-to-end test may be hard
+for many people who can't script other programs, but it provides
+something that can keep advanced people interested for longer.
 
 #### Automated testing (or full-cycle collaborative workflow)
 
@@ -74,7 +76,7 @@ collaborative exercise in the optional episode "Full-cycle
 collaborative workflow", and the instructor has a choice which one to
 teach (with the latter requiring around double the time). The
 exercise in Automated Testing can either be done as a type-along
-demonstration by the instructor or as an exercise in breakout rooms.  
+demonstration by the instructor or as an exercise in breakout rooms.
 
 **If run as an exercise, this episode requires that learners know how
 to set up Git repositories locally and online and how to work with
@@ -125,6 +127,12 @@ exercise and test design.
 
 ## Field reports
 
+### 2023 September
+
+For this lesson, "Motivation" and "Concepts" were combined.  An extra
+end-to-end test was added under "testing locally".
+
+
 ### 2023 March
 
 Due to a mix-up with instructors, we changed the plan at the last