A bit more doc details.

3 files changed, 48 insertions, 10 deletions

diff --git a/doc/breaking_rules.md b/doc/breaking_rules.md
index d5b399c..1a4b451 100644
--- a/doc/breaking_rules.md
+++ b/doc/breaking_rules.md
@@ -96,15 +96,25 @@ Even though this is a prototype, attention should be paid to basic craftsmanship
   supported by OpenLisp
 * Write one-sentence comments for at least each public fun and class
 * Use `assure`
-  to check the types of parameters in public interfaces
-* Some minimal documentation, at least an overview README file and man pages.
+  to check the types of parameters in public interfaces.
+  This should probably be done using `defcontract`.
+* Indent all the source code using Emacs.
+* Some minimal documentation, at least an overview README file
+\.[
+preston-werner 2010
+\.]
+and man pages
+\.[
+collyer cox
+\.]
+.
 
 ## Further Work
 
 This is probably the most work that makes sense
 without earning money.
 
-* Write contracts for public funs & classes
+* Write better pre- and post-conditions in contracts for public funs & classes
 * Could do simple multi-user,
   using the IRCv3 bots (nickserv, chanserv) and IRCCloud or similar
 
@@ -141,18 +151,35 @@ This was the subject of
 \.[
 bane 2008
 \.]
-. However, much of the work of dedicated documentation is better done in source code:
+. The output artifacts are a module guide an set of module interface specs.
+However, some of this documentation is better in the source code:
 
 * The summary of functions should be taken care of by having the public functions and classes commented.
 * The formal requirement for function behaviour is better done with contracts.
   Tables with Simple English are still a good idea for initial work.
-  
+
 ### UI
 
-This involves filling in any blanks that still need to be filled after the man pages have been written.
-There is also the system-level documentation to consider, some of which is fine in a README.
+The following can be added as sections to the README:
+
+* Uses hierarchy (but at a module level of granularity)
+* Task hierarchy
+
+And a proper software requirements spec should be written filling in any blanks that the man pages leave.  
 The specification of input and output variables is best left at the level of tables and Simple English again.
 
+## Testing
+
+Unit (olunit) tests should be derived from the module interface specs.
+Property-based testing would be nice here, but there doesn't seem to be a readily-available library.
+System tests should be derived from the requirements spec.
+It's ok for system tests to use the JSON-RPC interface.
+All tests should be automated,
+except possibly for the UI/view layer.
+
+Where there is scope to push some of the testing work "back" in the V model to contracts for the functions,
+this should be done instead.
+
 # Conclusion
 
 A method for developing software from an incomplete understanding of the requirements is given.
diff --git a/doc/refs b/doc/refs
index 5d000ea..2deb994 100644
--- a/doc/refs
+++ b/doc/refs
@@ -1013,3 +1013,14 @@
 %A Kent Pitman
 %T Accelerating Hindsight: Lisp as a Vehicle for Rapid Prototyping
 %D 1994
+
+%A Tom Preston-Werner
+%T Readme Driven Development
+%C San Francisco, CA, USA
+%D 23 Aug 2010
+%O available: https://tom.preston-werner.com/2010/08/23/readme-driven-development.html [accessed 27 May 2020]
+
+%A Geoff Collyer
+%A Russ Cox
+%T How to Write a Plan 9 Manual Page
+%O available: http://www.vitanuova.com/inferno/papers/manhow.pdf [accessed 27 May 2020]
diff --git a/free-fall.lsp b/free-fall.lsp
index 27dec85..a7cd918 100644
--- a/free-fall.lsp
+++ b/free-fall.lsp
@@ -1,10 +1,10 @@
 ;; TODO: air resistance, terminal velocity
-(defconstant +G+ 9.81)
+(defconstant +g+ 9.81)
 (defglobal *alt* 20000)
 (defglobal *v* 0)
 (defun step ()
    (setq *alt* (- *alt* *v*))
-   (setq *v* (+ *v* +G+))
+   (setq *v* (+ *v* +g+))
    (format (standard-output) "~A~%" *alt*))
 (defun my-main ()
    (while (> *alt* 0)
@@ -15,5 +15,5 @@
    (format (standard-output) "Gravitational constant: ~A~%" +G+)
    (format (standard-output) "Twice that: ~A~%" (* 2 +G+))
    (let* ((time 10)
-          (distance (* 0.5 +G+ (expt time 2))))
+          (distance (* 0.5 +g+ (expt time 2))))
          (format (standard-output) "Distance travelled in 10 seconds of free fall: ~A~%" distance)))