diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile | 4 | ||||
| -rw-r--r-- | doc/breaking_rules.md | 36 |
2 files changed, 33 insertions, 7 deletions
diff --git a/doc/Makefile b/doc/Makefile index 8e0f283..9cd37e5 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -11,9 +11,9 @@ all: breaking_rules.pdf breaking_rules.html breaking_rules.pdf: macros.ms breaking_rules.md refs.i ( cat macros.ms; lowdown -sTms breaking_rules.md ) | pdfroff -i -t -R -mspdf -k -Kutf8 > $@ -# Headers aren't emitted currently +# On macOS only, headers aren't emitted currently breaking_rules.html: macros.ms breaking_rules.md refs.i - ( cat macros.ms; lowdown -sTms breaking_rules.md ) | groff -Thtml -i -t -R -ms -k -Kutf8 > $@ + ( cat macros.ms; lowdown -sTms breaking_rules.md ) | groff -Txhtml -i -t -R -ms -k -Kutf8 > $@ refs.i: refs indxbib $^ 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. |