./venkatesh-prasad-ranganath/simpleExplanationsAreBetter.md

[timm]

After review, relabel to 'reviewTwo'. After second review, relabel to 'EditorsComment'.

[timm]

Review template

Before filling in this review, please read our Advice to Reviewers.

(If you have confidential comments about this chapter, please email them to one of the book editors.)

Title of chapter

While models are good, simple explanations are better

URL to the chapter

the markdown file.

https://github.com/ds4se/chapters/blob/master/venkatesh-prasad-ranganath/simpleExplanationsAreBetter.md

Message?

What is the chapter's clear and approachable take away message?

Less is More

Accessible?

Is the chapters written for a generalist audience (no excessive use of technical terminology) with a minimum of diagrams and references? How can it be made more accessible to generalist?

??

Size?

Is the chapter the right length? Should anything missing be added? Can anything superfluous be removed (e.g. by deleting some section that does not work so well or by using less jargon, less formulae, lees diagrams, less references).? What are the aspects of the chapter that authors SHOULD change?

ok. i'd add some stuff from the cogsci literature about how humans reason about the world w.r.t. differences; e.g. see "Redundancy Reduction and Pattern Recognition" in http://edge.org/responses/what-is-your-favorite-deep-elegant-or-beautiful-explanation. it turns out that frogs encoded by the world by differences is much more succinct that doing so with cocnent

Gotta Mantra?

We encouraged (but did not require) the chapter title to be a mantra or something cute/catchy, i.e., some slogan reflecting best practice for data science for SE? If you have suggestion for a better title, please put them here.

How about "Less is More (when explaining things to users)??

Best Points

What are the best points of the chapter that the authors should NOT change?

Interesting idea

Editorial

Got a lost a little.. wading thru paras 1,2,3,4... waiting for some "hook" that i can smile, snigger, smirk at. so i'd get tot the point, earlier

The section "Just tell us what is different and nothing more" might be worthy earlier. You could show them the punch line and the say something like "to illustrate this point, lets compare the "what is different" approach to the "tell me everything" approach which analysts are all to prone to use.

[devanbu]

Title of chapter

While models are good, simple explanations are better

URL to the chapter

https://github.com/ds4se/chapters/blob/master/venkatesh-prasad-ranganath/simpleExplanationsAreBetter.md

Message?

Models can be accurate/pertinent summaries of available data; but the model's message must be operationalized to be useful to developers.

Accessible?

The work is definitely understandable. However, I think the readability could be made a little better. I would suggest adding some sentences to clarify that a series of temporal logic models summarizes the behaviour of each driver (USB 2 and USB3). Since these are good summaries, the summaries contain within them (in latent fashion) the differences in the patterns. However, because there is a lot of information about each, the differences are not evident to a quick read.

Given enough time, presumably the devs could have figured it out; however, TL;DR applies, and the additoinal effort made by the authors helped win the day.

Size?

Is the chapter the right length? yes

Should anything missing be added?

May be some hints on how to operationalize models? Operationalization may involve simplifications/abstractions etc. Any gotchas?

Gotta Mantra?

All models are wrong. Some are Actionable. :-)

[tzimmermsr]

Great experience report @rvprasad !

Please take a look at the reviews and prepare a new version of the chapter by January 13. Focus on improving the readability of the chapter (see comments by @devanbu and @timm). I don't expect you to add the frog reference, but feel free to do so (if you see fit).

The chapter ends with an empty Reference section. Did you mean to add a pointer to where readers can learn more about the USB project.

[rvprasad]

Addressing @tzimmermsr

• no idea how to get bib-style references in markdown. Any pointers will be helpful. In the meantime, I will use manually crafted references.

[rvprasad]

Addressing @devanbu comments

• Added more information explaining the patterns (bulleted list)
• Added the rationale as to why patterns were used to compare driver behaviors. (end of section 1)
• Added a brief comment on other aspects involved in operationalizing the model (end of section 3)

[rvprasad]

Addressing @timm comments

• Since the article is about simplifying the explanation and difference presentation is one approach to simplification, I am not sure the cogsci reference will provide info relevant to data analysis in general (as opposed info relevant to the current example). Please let me know if you think otherwise.
• Sections 1 and 2 set up the context to how we can complicate presentation with data analysis. Section 3 then pokes hole in this context to highlight the mistake. So, I have left the flow as is.
• As a hook, at the end of the introduction, I have summarized the incarnation of "KISS" that I encountered in my experience.

[rvprasad]

Thanks to all the reviewers for their feedback. I have tried to incorporate/address your comments/concerns to the best extent possible. Please let me know if you have further inputs.

[tzimmermsr]

Thank @rvprasad This looks great. I like the changes that you made.

--Tom

[timm]

@tzimmermsr : I'm closing issues where we have gotten to "good to go" to MK. can you do the same here?