markdown for design and implementation (WIP)

Overview

• use .md to describe design, user another .md to describe implementation (multiple views)

• add @ syntax to create and ref other .md files
• implementation is bash or python or whatever
• observation:
  • disease: trying to fit everything onto one notation
  • cure: use multiple views and multiple notations, all very similar to .md and to bash
• diagram:
  • only one way to view a design/implementation
  • currently using drawio https://www.diagrams.net
• text:
  • only one way to view a design/implementation
  • bash is textual
  • python is textual
  • JavaScript is textual
  • .md is textual
• asynchronous
  • all components are asynchronous
  • all components are concurrent (can be run in parallel, but not necessarily)
    • note that all parallel designs are subsets of concurrent designs
    • parallelism is an implementation detail
    • concurrency is a design paradigm, though

Refinement

The “most interesting” question is: “what happens to my original idea(s) when I refine the idea(s)”

[This also applies to TODOs - how do you refine/embellish a TODO item?].

For example, I have an item and I begin to envision doing it in two steps.

Do I re-write the item, or, do I “push into” the item (open a new file, zoom in on a diagram element, etc.)?

How does the editor “remember” what was there and how does it represent the newer version?

This step is recursive. Once I’ve broken an item down into two parts, what happens if I want to break down one of the parts into two more parts? And so on…

Edit operations

• add node
• connect node
• ref to other .md file
• butted rectangles means sequence (synch)
• SVG rect, ellipse, text, line
• line beginning with @ means other-file with given name (includes spaces) e.g. @ all containment means other-file called all containment.md
• rename @node (hence, rename file)
• push selection to new .md file (invent @ name, allow change later)

Stubs

Not all steps are automated, some require human intervention.

Begin with outline of steps, all non-automated, i.e. implementation is English text.

Refine steps by replacing them with automation.

Round Trip

Q: How does refining a step reflect back to the original design?

Q: Is the original design the master document?

Q: Do we combine the original design with implementation to produce an app?

• initial version: git-like folding of implementation onto design, complain if mis-match (conflict) ie. implementation does not fit neatly over design
• AOP for aspects of implementation?, Lisp-like :before and :after
• Paul Bassett’s “Framing Software Reuse” for creating app from design+implementation?

Implementation

Q: Use bash’s #!~/bin/ag as first line of implementation?

Example

See Also

Blog
References