Usethis: Feedback on setup article

[jennybc]

@maelle encouraged me to centralize advice re: setting up one's system for R development, esp. if using usethis.

Here is that article:

http://usethis.r-lib.org/articles/articles/usethis-setup.html

Unfortunately it's not a PR that can be easily reviewed, but I would still appreciate any feedback.

Goal: help someone do all of their setup at once. Or at least understand the general scope of this task. It is disappointing to keep using functions and learn gradually and indirectly about all the setup you need to do in order to truly enjoy usethis.

Not the goal: I do not want to get sucked into detailed instructions for setting up a dev environment. This is not a good place for that.

[jennybc]

I am also walking this very fine line:

usethis does not actually use or need system Git. But I have to mention system Git for two reasons:

1. libgit2 and therefore git2r and therefore usethis do share setup with system Git. So git config, git ignores, cached credentials, ssh keys.
2. No sane person would ever use the Git-related functions in usethis w/o also ... using Git! So of course they must have Git installed, even if usethis itself doesn't call it.

[batpigandme]

This is great, Jenny. I made a PR with minor edits. The only thing I didn't change, but thought about changing was maybe bullet-ifying the Connections: Git, GitHub, RStudio and maybe cutting a little bit down, in favour of assuming they'll go to Happy Git.

[jennybc]

Thanks @batpigandme, merged.

I took a quick look at the Connections section. I think every sentence is there for a reason even though, yes, it does link out to Happy Git. I will leave for now. We can continue to refine this once users actually attempt to use it. I'm not baking it into the package as a vignette. The web version is definitive and, therefore, easy to keep fresh.

[batpigandme]

Makes sense. One of the reasons that I didn't actually edit it was that there wasn't anything extraneous jumping out at me.

[maelle]

I liked the way you had introduced the list to me "to have full usethis bliss", maybe you could add the phrase to the article?

[maelle]

I have a general question, do you folks have some style preference regarding package names in text, i.e. is there a reason for you not to highlight their names?

[jennybc]

I have a general question, do you folks have some style preference regarding package names in text, i.e. is there a reason for you not to highlight their names?

Yeah the house style is to not format package names and, especially, to not back tick them as if they are code.

http://style.tidyverse.org/code-documentation.html#code-font

Do not use code font for package names. If package name is ambiguous in the context, disambiguate with words, e.g. “the foo package”.

I sense there is some vague discomfort with this. I think @jimhester has been known to put a package name in bold or ... does that on the first occurrence. cc @hadley

[batpigandme]

In the privacy of my own writing, I often backtick packages just to make them stand out visually. However, I think linking to a package on first mention ~accomplishes the same thing.

[hadley]

I think we should standardise on linking to package site on first use.

[batpigandme]

I like that, because it's something I'd like to request in community from conscientious askers— like, saves the reader from having to google it, and they probs already have that window open…

[jennybc]

This has been merged: http://usethis.r-lib.org/articles/articles/usethis-setup.html