Reorganize folder structure; merge into a single task

Author: rafd

README.md

@@ -15,15 +15,28 @@ In the first hour, we will do a brief explanation of data-driven APIs, and then
  - participants submit their solutions for critique
  - review and discussion of solutions
 
-## The Katas
 
- 0. [Maybe something here]()
+## Your Design Task
 
- 1. [Designing a data-driven DSL based on an existing declarative DSL](/docs/data-driven-by-porting.md)
+1. Choose one of the problem domains from [this list](./problem-domains.md).
 
- 2. [Designing a data-driven DSL from scratch](/docs/data-driven-from-scratch.md)
+   We recommend choosing a problem domain that you are at least somewhat familiar with (to better understand how your syntax might be used in practice).
 
+   If you've thought of other problem domain that you'd like to design a data-driven API for, go ahead!
 
-After you're done with any of the exercises, if you'd like to have them potentially discussed in Part 2 of the workshop, add a link to [the spreadsheet](https://docs.google.com/spreadsheets/d/1F7TGID104-ayVhOT47RV3fCLHpvAaeOGZScIKdvG9-8/edit?usp=sharing).
+
+2. Design a data-driven DSL for that problem domain.
+
+   give some examples of how you would use it.
+
+   see [the template](./template.md)
+
+   The task is *not* to implement the system, it is just to design the data-driven API.
+
+   You do not have to implement the entire language, just use the existing language as inspiration.
+
+3. Reflect using [these questions](./evaluating-notations.md)
+
+4. After you're done with your design(s), if you'd like to have them potentially discussed in Part 2 of the workshop, add a link to [the spreadsheet](https://docs.google.com/spreadsheets/d/1F7TGID104-ayVhOT47RV3fCLHpvAaeOGZScIKdvG9-8/edit?usp=sharing).
 
 

docs/data-driven-by-porting.md

@@ -1,40 +1,42 @@
-### ERD Diagrams
 
-Like DOT, but, just for ERD diagrams. (A more limited domain might allow for a simpler syntax)
 
 
-### Argument Parsing
+ ### Modeling Physical Systems (Modelica)
 
-“data driven ‘spec’ for what a commandline can take in”,
-    What would the extracted data look like?
+ Modelica is a language used to model complex systems, such as the electrical and mechanical subsystems of a car. Modelica lets you define components (such as a "resistor") with input and output "pins", define equations that related the various inputs and outs (ex. `V = IR`), and then hook up and simulate a network of components.
 
-`./program -l -p 8080 -d /usr/logs -g a,b,c,d,e`
+ Resources
+  - [Modelica by Example (Book)](https://book.xogeny.com/)
+  - [Modelica on Wikipedia](https://en.wikipedia.org/wiki/Modelica)
 
 
-### ACL on Data Structures
+### System Dynamics
 
-Representing ACL rules on certain fields (to then be used to ‘filter’ data structures)
+ representing System Dynamics (stocks and flows)
+    https://en.wikipedia.org/wiki/System_dynamics
 
 
-### Finite-State Machines
-  https://en.wikipedia.org/wiki/Finite-state_machine
-
+### Mathematical Notation
 
+https://en.wikipedia.org/wiki/TeX#Mathematical_example
 
+for generating, manipulating and then..
+      … converting for use in latex
+              … converting for use in a symbolic math system (Maple, Mathematica)
 
-### End-to-End Testing
 
-declarative format to run E2E tests
+### Gherkin
 
-can do so w/ full support of language
-but, since the domain is pretty limited (visit url, click button 'x', check for value 'y', etc.), could a data-driven syntax work?
+Gherkin is a language used for writing BDD test cases.
 
+Resources
+- [Gherkin on Wikipedia](https://en.wikipedia.org/wiki/Cucumber_(software)#Gherkin_language)
+- [Gherkin Docs](https://cucumber.io/docs/gherkin/reference/)
 
-https://github.com/teamcapybara/capybara
-https://en.wikipedia.org/wiki/Selenium_(software)
-https://developers.google.com/web/tools/puppeteer
 
+### Describing Language Grammars (Instaparse)
 
+[Instaparse](https://github.com/engelberg/instaparse) is an existing Clojure library for describing context-free grammars, but it uses an [EBNF](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form) based custom-string syntax. What might it look like if it was data-driven?
 
 
 ### Musical Notation
@@ -50,21 +52,88 @@ https://en.wikipedia.org/wiki/MusicXML
 
 
 
+### Dockerfiles
 
-### Mathematical Notation
 
-https://en.wikipedia.org/wiki/TeX#Mathematical_example
+### Describing Graphs (DOT / GraphViz)
 
-for generating, manipulating and then..
-      … converting for use in latex
-              … converting for use in a symbolic math system (Maple, Mathematica)
+DOT is a language used for describing graphs (the nodes-and-vertices kind, not the bar-chart kind). Tools like GraphViz consume DOT files and use various algorithms to render the graphs.
 
+Resources
+- [DOT on Wikipedia](https://en.wikipedia.org/wiki/DOT_(graph_description_language))
+- [Lots of Examples](http://graphviz.org/gallery/)
 
-### System Dynamics
 
- representing System Dynamics (stocks and flows)
-    https://en.wikipedia.org/wiki/System_dynamics
+### rake
+
+Rake is a language used to describe tasks and dependencies in the context of software build automation.
 
+define tasks, with optional multiple dependencies
+
+Resources
+- [Rake on Wikpedia](https://en.wikipedia.org/wiki/Rake_(software))
+- [Martin Fowler's Intro to Rake](https://martinfowler.com/articles/rake.html)
+
+
+### AWK
+
+AWK is a language for extracting and manipulating data from text files.
+
+Resources
+- [AWK on Wikipedia](https://en.wikipedia.org/wiki/AWK)
+
+
+### XSLT... for EDN?
+
+XSLT is a language for describing transformations of XML documents in XML syntax.
+
+Perhaps, it'd be possible to create a similar language for transforming EDN documents in EDN?
+
+Resources
+ - (XSLT on Wikipedia)[https://en.wikipedia.org/wiki/XSLT]
+
+
+### Board Games
+
+https://en.wikipedia.org/wiki/Portable_Game_Notation
+https://en.wikipedia.org/wiki/Smart_Game_Format
+
+
+### ERD Diagrams
+
+Like DOT, but, just for ERD diagrams. (A more limited domain might allow for a simpler syntax)
+
+
+### Argument Parsing
+
+“data driven ‘spec’ for what a commandline can take in”,
+    What would the extracted data look like?
+
+`./program -l -p 8080 -d /usr/logs -g a,b,c,d,e`
+
+
+### ACL on Data Structures
+
+Representing ACL rules on certain fields (to then be used to ‘filter’ data structures)
+
+
+### Finite-State Machines
+  https://en.wikipedia.org/wiki/Finite-state_machine
+
+
+
+
+### End-to-End Testing
+
+declarative format to run E2E tests
+
+can do so w/ full support of language
+but, since the domain is pretty limited (visit url, click button 'x', check for value 'y', etc.), could a data-driven syntax work?
+
+
+https://github.com/teamcapybara/capybara
+https://en.wikipedia.org/wiki/Selenium_(software)
+https://developers.google.com/web/tools/puppeteer
 
 
 ### Chemical Formulas
@@ -76,7 +145,6 @@ https://www.webqc.org/balance.php
 https://en.wikipedia.org/wiki/International_Chemical_Identifier
 
 
-
 ### Chemical Structural Formulas
 
 Representing the molecular structure of a complex compound, for the purpose of then generating a diagram (one or more of: skeletal diagram, Lewis dot diagram, etc.)
@@ -90,8 +158,8 @@ https://en.wikipedia.org/wiki/International_Chemical_Identifier
 http://www.xml-cml.org/documentation/index.html
 
 
-
 ### Board Games
 
 https://en.wikipedia.org/wiki/Portable_Game_Notation
 https://en.wikipedia.org/wiki/Smart_Game_Format
+