about summary refs log tree commit diff stats
path: root/doc/breaking_rules.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/breaking_rules.md')
-rw-r--r--doc/breaking_rules.md36
1 files changed, 31 insertions, 5 deletions
diff --git a/doc/breaking_rules.md b/doc/breaking_rules.md
index aa3cb89..d5b399c 100644
--- a/doc/breaking_rules.md
+++ b/doc/breaking_rules.md
@@ -22,6 +22,8 @@ beck 1999
 I argue that improvements in development tools have
 invalidated this.
 
+*TODO*: case study
+
 *Colophon*: this document tries to depend only on GFM,
 in the same spirit as the software.
 The use of tools like
@@ -81,9 +83,8 @@ but there is no need to force it at the start.
 
 A JSON-RPC library was not difficult to write.
 
-## Imperative/Object-oriented paradigm
-
-Here, the following technology is recommended:
+It was decided to use the imperative/object-oriented paradigm.
+The following technology is recommended:
 
 * The OpenLisp interpreter.
 * Emacs for the view layer
@@ -98,7 +99,7 @@ Even though this is a prototype, attention should be paid to basic craftsmanship
   to check the types of parameters in public interfaces
 * Some minimal documentation, at least an overview README file and man pages.
 
-### Further work
+## Further Work
 
 This is probably the most work that makes sense
 without earning money.
@@ -109,7 +110,9 @@ without earning money.
 
 # Refinement to Production-Quality
 
-I argue that there is a repeatable procedure to improve the quality of a
+First, software at the level of the previous section is quite usable.
+It should be confirmed that further improvement is, in fact, required.
+If so, I argue that there is a repeatable procedure to improve the quality of a
 (reasonably well-written) prototype to a releaseable product.
 
 First, ensure that the surrounding infrastructure is in place:
@@ -127,6 +130,29 @@ Then, the following code & documentation improvements should be made:
 * Port some of the trivial-\* CL libraries from quicklisp where justified.
 * Port to core-lisp on platform.sh?
 
+## Documentation Details
+
+I think it is a good idea to keep the separation between library and UI code.
+And JSON-RPC is perfectly adequate for that.
+
+### Library
+
+This was the subject of
+\.[
+bane 2008
+\.]
+. However, much of the work of dedicated documentation is better done in 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 specification of input and output variables is best left at the level of tables and Simple English again.
+
 # Conclusion
 
 A method for developing software from an incomplete understanding of the requirements is given.