Reviewer 1 Comments

[emhart]

• [x] Rules 4 and 5 seem like variations on the same rule -- keeping the data accessible. It would be helpful to differentiate these rules a bit more.
• [X] Line 21: is a good advice => is good advice
• [x] Line 136: States that an example of machine readable open format that would not be easy to process include Microsoft word, but in the preceding rule (Rule 4) it states that Microsoft excel is not an open format. Perhaps just keep PDF as the example.
• [x] Lines 140-144: discussing source code doesn't really fit in this section. Perhaps move these lines to the section about metadata (Rule 7).
• [X] Line 147: variable is a column => variable as a column
• [X] Line 147-148: unit is a table => unit as a table
• [X] Line 161: standards-compliant data, it is easier to build
• [x] Line 164: The section on semantic versioning is well received
• [X] Line 200: meta-data in in well => meta-data in well
• [X] Line 201: Extraneous close paren ) after JSON
• [x] Line 244: Seems like an appeal to authority. Replace explicit reference to Kristen Briney
• [x] Line 245: Include a caution with respect to Rule 8 (ensure that the offsite "cloud" storage is as secure as the primary storage)
• [X] Line 311: include oxford comma "animals, fungi, and microbes"
• [X] Line 337-338: ways to programatically query databases through

[karawoo]

Regarding the comment about rules 4 and 5, maybe we should change rule 5 to something like "Data should be structured for analysis" or similar. We could cite Vince Buffalo's quote that one should "write code for humans, write data for computers" and move the paragraph beginning "To take full advantage of data..." up to the beginning to establish this point early on.

[fmichonneau]

I like your ideas @karawoo !

I think moving the paragraph starting with "To take..." at the beginning makes sense.

Initially, rule 5 was called "Data should be stored in a machine-readable format" and I think that calling it "structured for analysis" makes the intention behind this idea clear.

[naupaka]

I 3rd @karawoo's idea to rename Rule 5 and move the "To take..." paragraph to the top of the section. The current first paragraph under Rule 5 could almost fit better under rule 4, as well.

I think the antecedents for that VB quote include Donald Knuth (1984) in Literate Programming (italics in original)

Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.

and Martin Fowler (1999) in Refactoring: Improving the Design of Existing Code

Any fool can write code that a computer can understand. Good programmers write code that humans can understand.

[karawoo]

Ok, since several people are on board with this I'll create a PR later today and we can discuss it more there if needed.

On Sat, Apr 30, 2016 at 12:00 PM, Naupaka Zimmerman < notifications@github.com> wrote:

I 3rd @karawoo https://github.com/karawoo's idea to rename Rule 5 and move the "To take..." paragraph to the top of the section. The current first paragraph under Rule 5 could almost fit better under rule 4, as well.

I think the antecedents for that VB quote include Donald Knuth (1984) in Literate Programming (italics in original)

Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.

and Martin Fowler (1999) in Refactoring: Improving the Design of Existing Code

Any fool can write code that a computer can understand. Good programmers write code that humans can understand.

— You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub https://github.com/emhart/10-simple-rules-data-storage/issues/126#issuecomment-215987435

[emhart]

The last of these have been taken care of with PR #137