Documentation refresh

[jennybc]

Pulling some side observations out of #130

@jennybc said:

It doesn't seem like here really advertises the criteria is uses for finding the project directory. And empirically it seems like a lot of people think that only an .Rproj file "works"... where to have a bullet list of the project root criteria used by here?

@krlmlr said:

It might be time to evaluate the use of i_am() in the wild and adapt the documentation around the intended use cases. The current focus of the "Get Started" vignette on i_am() is confusing, perhaps this really should be another vignette, and a true "Get Started" meets users at all levels where they are.

[jennybc]

@krlmlr To clarify: are you saying that you're open to backing off on this sentiment:

The intended use is to add a call to here::i_am() at the beginning of your script or in the first chunk of your rmarkdown report. Prior to version 1.0.0, it was recommended to attach the here package via library(here).
This still works, but is no longer the recommended approach.

and, instead, to restore simple here::here() (or library(here);...; here(...)) use, with no initial call to here::i_am(), as usage that's viewed as OK again (?).

I would certainly be happy about this change.

Assuming my interpretation is right, yes, I'd love to see simple here::here() presented as perfectly valid usage for most folks / most situations. Then the more involved, but safer, here::i_am() approach could be its own vignette.

And, regardless, the default here criteria could also be exposed in more places. Since I opened this issue, I became aware (oh, so aware! 😬) that these are, in fact, documented in:

https://here.r-lib.org/reference/here.html#project-root

I think it would be great to include that list in "Get started" or maybe even on the home page. It seems many people mistakenly think .Rproj is the only way to recognize a project root directory and I'd love to make the documentation more clear that this is not the case.

[jennybc]

More docs brain dump: Another confusion I've seen several times is that here() rediscovers project root at the moment it's called. Whereas it's more like, here() discovers project root at the moment it's first called. I know this is documented, but it seems there's still room to make this more clear.