Blog post generator

1 files changed, 136 insertions, 0 deletions

diff --git a/doc/breaking_rules.md b/doc/breaking_rules.md
new file mode 100644
index 0000000..aa3cb89
--- /dev/null
+++ b/doc/breaking_rules.md
@@ -0,0 +1,136 @@
+title: Breaking the Rules: Refining Prototypes Into Products  
+author: Darren Bane  
+copyright: 2020 Darren Bane, CC BY-SA  
+
+# Abstract
+
+Recommendations for a process to refine prototypes into production-quality code
+are made.
+\.R1
+accumulate
+\.R2
+
+# Introduction
+
+The conventional wisdom is that prototypes should be discarded once the lessons
+have been learned,
+and the final product written again from scratch.
+In the spirit of
+\.[
+beck 1999
+\.]
+I argue that improvements in development tools have
+invalidated this.
+
+*Colophon*: this document tries to depend only on GFM,
+in the same spirit as the software.
+The use of tools like
+PP, PlantUML and Pandoc is postponed indefinitely.
+
+# Literature Review
+
+There is a long history of recommending prototyping as a way to construct
+systems.
+I would personally recommend
+\.[
+robertson agust\(i 1999
+\.]
+and
+\.[
+pitman 1994
+\.]
+.
+
+A closely related are is that of "specification animation",
+quickly writing an implementation of some subset of a formal specification in
+for example Z or VDM.
+Prolog is a common choice for this, but I choose Lisp instead.
+
+However, as stated in the introduction, this document differs from these in
+arguing that it is possible to *refine* a prototype into a product.
+
+# Prototyping
+
+The first step is to construct a prototype,
+or in modern terminology a "Minimal Viable Product".
+These recommendations follow on from
+\.[
+robertson agust\(i 1999
+\.]
+and
+\.[
+bane 2008
+\.]
+.
+
+Reasons for choosing ISLisp include:
+
+* Procedural and object-oriented programming is commonly taught.
+  And seems to be easier to learn.
+* A disregard for popularity (which Common Lisp, or Java would win).
+  In fact, the language seems more popular in France and Japan than
+  the USA.
+* The efficiency gain from an integrated environment.
+  With Emacs and JSON-RPC it's not totally integrated, but is close.
+  ELisp and ISLisp are not identical but are very similar.
+* Contrary to a lot of other languages, it is fairly paradigm-agnostic.
+
+Unlike Prolog,
+users may end up writing logic eventually for DbC
+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:
+
+* The OpenLisp interpreter.
+* Emacs for the view layer
+* JSON-RPC for inter-process communication
+
+Even though this is a prototype, attention should be paid to basic craftsmanship:
+
+* Divide the system into packages, using at least the subset of CL that is
+  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.
+
+### Further work
+
+This is probably the most work that makes sense
+without earning money.
+
+* Write contracts for public funs & classes
+* Could do simple multi-user,
+  using the IRCv3 bots (nickserv, chanserv) and IRCCloud or similar
+
+# Refinement to Production-Quality
+
+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:
+
+* Configuration management. The prototype should already have been checked into git.
+* Build. TODO: Read the recommendations in the OpenLisp manual?
+* Test.
+  Write olunit
+  test cases for any scenarios that aren't coverered by DbC.
+* Track. Start using a defect tracking system.
+
+Then, the following code & documentation improvements should be made:
+
+* Document the system more exhaustively
+* Port some of the trivial-\* CL libraries from quicklisp where justified.
+* Port to core-lisp on platform.sh?
+
+# Conclusion
+
+A method for developing software from an incomplete understanding of the requirements is given.
+It is hoped that this is more effective than most of what is currently-used.
+\.[
+$LIST$
+\.]