Some tweaks + suggestions

[maelle]

• I found it confusing that there was keyring as the package name and keyring as the thing where secrets are stored. Actually maybe add a sentence saying "Keyrings are the objects where the keyring package stores secrets" or something similar?
• I removed the Latin "e.g." in favor of the more readable "for instance".
• I wrote "environment variables" in full.

I wonder whether there could be two links

• one explaining what an OS' credentials store is;
• one about environment variables in R, like https://rstats.wtf/r-startup#renviron but not only .Renviron

Second to last suggestion, could there be a comparison of workflows, like

## Without using keyring

1. The user set an environment variable `MYSECRET="super-secret"` 
    - in a project-specific `.Renviron`, hopefully gitignored;
    - or in the user `.Renviron`;
    - or types `Sys.setenv(MYSECRET="super-secret")` in the console, hopefully protecting `.Rhistory`.
1. The package retrieves the secret with `Sys.getenv("MYSECRET")`.

## With keyring

1. The user stores the secret using `keyring::key_set("MYSECRET")`, typing interactively so nothing is recorded in `.Rhistory`.
1. The user sets an environment variable with `Sys.setenv(MYSECRET = keyring::key_get("MYSECRET"))` in a script for instance.
1. The package retrieves the secret with `Sys.getenv("MYSECRET")`.

Last suggestion, for a package developer, most often keyring is more something to document than to use, correct? In a package using secrets you'd recommend a certain workflow or point user to keyring, but not use it inside your code?

[maelle]

Further thought after updating my local GitHub PAT using gitcreds: maybe there could be a mention of gitcreds, to underline the parallels between the two? I used to store my local GitHub PAT in .Renviron.

[gaborcsardi]

Thanks!

[gaborcsardi]

In general I am wary of putting too many links into the documentation, these links tend to go stale. It is a lot of work to make sure they point to the right place. If people don't know what environment variables are, they can google "environment variables" and probably get a good link. I think extensive links and workflow suggestions are better suited to blog posts, or tutorials, and not so much for the reference manual or the README.

[maelle]

For info @gaborcsardi I came here via r-lib/httr2#346