improving readability about reproducibility-guide HOT 7 CLOSED

What Lin said.

For that matter, if we're going to pick apart the writing:

"growing and changing frequently" is kind of redundant and nonsensical. Pick two, and if you're going to use the adverb, it goes before the verbs, i.e. "frequently changing" or "growing and changing". Neither "growing frequently" nor "frequently growing" makes sense.

Commas are your friends! Learn to use them!

Avoid pseudo-quantitative phrases like "a number of", and use the right word for the job. "detailed" is not the same as "described".

Be succinct wherever possible. Especially on the web, nobody wants to read verbose text.

The next sentence could read more like this:

original (run-on): We have included a collection of annotated links below that provide additional information about the tools that are included in a number of the workflows detailed on this site

suggested revision: The following links provide additional information about the tools referenced on this site.

"preview views" should probably be replaced with "screenshots"?

Also, this is a great list of tools, but I don't see any discussion of how these particular tools are more reliable/reproducible than others? I personally have had problems with even day-to-day reproducibility with Rstudio, for example. Some of them contribute indirectly, by providing support for better communication.

So: how do these tools specifically contribute to reproducibility? Maybe this is elsewhere, but it's worth mentioning somewhere on this page. Where's the discussion of "Best Practices" for R code, and recommendations for how to write the best documentation to go along with the code?

e.g. I recently got a copy of Jeff Knupp's e-book on Writing Idiomatic Python. Does such a thing exist for R? If it doesn't exist yet, maybe this is a good time to sketch out a "table of contents" for what is forthcoming? I know some people have committed to writing blog posts on specific topics.

from reproducibility-guide.

@lincrampton and @szeitlin, love the pickiness on the writing! I am not married to any of the writing. I agree with all of your suggests. If you guys want to go ahead and make these changes, that would be great.

@szeitlin I think it would be a great addition to add why the tools increase reproducibility. As I am learning (from talking about the project with colleagues), conveying the "whys" in reproducibility is important....and surprising difficult. I would also like to include on this site the very best tutorials we can find on each of these tools and incorporate/link them.

Which brings me to the last point, uniting/incorporating other people's writing on the subject. I really want this site to be a uniting of information already out there, rather than trying to reinvent the wheel for every topic (which causes further segregation of info) . @szeitlin, please include links to the blogs you were talking about, maybe we can contact the authors. Depending on the author and licensing, maybe we can re-publish their work here adding credit to their original posts. For instance, @kbroman has given his full support to republish/remix all his great tutorials. I really like thinking of this site as a curation of material. Reproducibility practices are not established yet, so we need as much input from the community as possible.

from reproducibility-guide.

@lincrampton and @szeitlin, thanks for your thoughtful input and catching some weak spots, will you be forking the repo and editing directly? That would be most helpful and welcome!

@szeitlin Your question 'how do these tools specifically contribute to reproducibility?' is part of my plan for the introduction, which is a work in progress. That's a great question though, and I'll use it as a heading. The short answer is that these tools provide an efficient workflow for literate programming with R.

As for "Best Practices" for R code, I think https://github.com/hadley/adv-r (specifically http://adv-r.had.co.nz/Style.html) is probably the best candidate for that at the moment. There are a couple of SO posts that point to other useful resources, here's one: http://stackoverflow.com/a/2258292/1036500 We could have a section in the 'further reading' page to point people to these resources. @szeitlin perhaps you could contribute a section here on (or pointing to resources on) best practices for writing R code?

from reproducibility-guide.

As for grammar and spelling: I tried to fix a few of the issues today, but there might still be a few.

from reproducibility-guide.

ok I will put this on my to do list! Will be helpful for me anyway.

Sam

Ben Marwick mailto:[email protected]
May 5, 2014 10:18 PM

@lincrampton https://github.com/lincrampton and @szeitlin
https://github.com/szeitlin, thanks for your thoughtful input and
catching some weak spots, will you be forking the repo and editing
directly? That would be most helpful and welcome!

@szeitlin https://github.com/szeitlin Your question 'how do these
tools specifically contribute to reproducibility?' is part of my plan
for the introduction, which is a work in progress. That's a great
question though, and I'll use it as a heading. The short answer is
that these tools provide an efficient workflow for literate
programming with R.

As for "Best Practices" for R code, I think
https://github.com/hadley/adv-r (specifically
http://adv-r.had.co.nz/Style.html) is probably the best candidate for
that at the moment. There are a couple of SO posts that point to other
useful resources, here's one:
http://stackoverflow.com/a/2258292/1036500 We could have a section in
the 'further reading' page to point people to these resources.
@szeitlin https://github.com/szeitlin perhaps you could contribute a
section here on (or pointing to resources on) best practices for
writing R code?

—
Reply to this email directly or view it on GitHub
#48 (comment).

lin crampton mailto:[email protected]
April 29, 2014 8:19 AM

http://ropensci.github.io/reproducibility-guide/sections/tools/
para 1: lose the extraneous 'to'
“All the tools listed to here are free,” should read:
“All the tools listed here are free. “

|is it 'Markdown' or 'markdown'? should be consistent.
“a list of applications that provide support for authoring in Markdown”
“including a basic tutorial on markdown”

is it 'html' or 'HTML'? should be consistent.
“html in current release, additional formats in preview release”
“An R Markdown document can also be converted to standalone HTML file”
|

—
Reply to this email directly or view it on GitHub
#48.

from reproducibility-guide.

Thanks @szeitlin. I loved the edits you put in. Should I just leave this issue open? As it is always a section that could be worked on. That way people who are unfamiliar with Github can leave suggestions of edits directly in this issue section.

from reproducibility-guide.

good, glad you liked them.

I think it makes sense to leave it open. I might contribute more myself.

sam

Ciera Martinez mailto:[email protected]
May 19, 2014 11:09 AM

Thanks @szeitlin https://github.com/szeitlin. I loved the edits you
put in. Should I just leave this issue open? As it is always a section
that could be worked on. That way people who are unfamiliar with
Github can leave suggestions of edits directly in this issue section.

—
Reply to this email directly or view it on GitHub
#48 (comment).

lin crampton mailto:[email protected]
April 29, 2014 8:19 AM

http://ropensci.github.io/reproducibility-guide/sections/tools/
para 1: lose the extraneous 'to'
“All the tools listed to here are free,” should read:
“All the tools listed here are free. “

|is it 'Markdown' or 'markdown'? should be consistent.
“a list of applications that provide support for authoring in Markdown”
“including a basic tutorial on markdown”

is it 'html' or 'HTML'? should be consistent.
“html in current release, additional formats in preview release”
“An R Markdown document can also be converted to standalone HTML file”
|

—
Reply to this email directly or view it on GitHub
#48.

from reproducibility-guide.