From 8eb74012ad702d59b6b8a3c18e86f7755172de72 Mon Sep 17 00:00:00 2001 From: Mike Thompson Date: Thu, 22 Feb 2018 21:05:26 +1100 Subject: [PATCH] Update README.md --- README.md | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index e0f23d1..5336d13 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ `re-frame-10x` lets you instrument, and then inspect, the inner workings of a running `re-frame` application. It presents as a programmer's dashboard, delivering curated insight and illumination. -It helps you find false assumptions faster. +It helps you to find false assumptions faster. ## Show Me @@ -35,40 +35,41 @@ of trace data. ### It Is About The Data Flow -While re-frame is a functional framework, it is -strongly defined by its "data oriented" design. `re-frame` +`re-frame` is a functional framework but it's design is "data oriented". It "flows" data, in a loop, through the functions you provide. -To understand what is happening in a `re-frame` app, you must understand +To understand what is happening in your `re-frame` app, you must understand what data is "happening". ### It Is Always About The Data -So, clearly, data is at the core of `re-frame-10x` for both of the reasons -just outlined, but its importance is even more base and fundamental than that. +So, that's two good `re-frame`-specific reasons why data is at the core of +`re-frame-10x`, but actually, the importance of data is even more fundamental +that that. Each time you put a `println` into your program, you are printing out what? And why? Invariably, it is data which fuels your debugging investigation, confirming your current hypothesis, or not. -And when you write your unittests, you represent your expections as what? Correct -data is the very definition of success. +And when you write your unittests, you represent your expections as what? Code is proved +correct by the data it produces. -So, for debugging and understanding activities, more data, more easily is winning. Going back -and adding a `println` shouldn't be necessary. All the data you need should already -be captured, and it should be readily available in your REPL for further experimentation. +So, for debugging and understanding activities, "more data, more easily" is winning. If +`re-frame-10x` does its job, it shouldn't be necessary for you to add `printlns`. +The data you need should be captured and presented, and, if further experimentation +is required, it should be available in your REPL too. ### Data Brings Code To Life Perhaps you have seen LightTable in action? In the small, it is a delightfully productive debugging environment because it co-renders -code and the data generated by running the code. The data provides a "paper trail" which +code with the data generated by running the code. The data provides a "paper trail" which brings the code to life, revealing its dynamics and enriching a programmer's understanding. `re-frame-10x` has a similar goal, although the method is different. -### It Is A Data Dashboard +### It Is A Data Dashboard Observing raw data trace is both interesting and valuable, but it isn't enough. First, we want to leverage this data for insights. And, second, there's often too much data - you @@ -113,7 +114,7 @@ features, and build a cognitive map of how the code is structured. Internal discussion about a name meandered for a while. Initially, it was `re-frame-trace`, which is accurate, sure, but it is also 100% sausage because it talks about low level function, and not higher level benefit (sizzle, sizzle). Side stepping the issue, I wanted to call it `vox-datum` (voice of the data) but that was cruelly rejected, for reasons I don't care to remember. The pain. I mean, who the hell doesn't like a Latin name?? Philistines. -Now, the tool's benefits are `-insight` and `-illumination`, but adding either made the name waaaay too long. Naming things - it really is a nightmare! +If benifit was a must, then there was `-insight` and `-illumination`, but adding either made the name waaaay too long. Naming things - it really is a nightmare! Finally, `-10x` cheekily materialised, delivering 100 decibels of audacious sizzle, and consequently a challenge for us to live up to. A 10x programmer starts by having 10x more knowledge and insight - so go make that tool, smarty pants.