Closed pkq closed 6 years ago
Yes, this is an interesting idea, and is what I've got in mind for a longer-form vignette document. For the README we do want to keep it as short as possible, and focused on giving the user a quick start by copy-pasting a few key functions.
In the vignette we can take the approach your describe, and give more motivation and context for each step, and maybe some flow diagrams showing different combinations of the steps, depending on the user's needs. If you'd like to make a start on a vignette outline along these lines, that would be most helpful.
We'll do this in a vignette.
Sounds good, thanks! Probably won't have time to work on a vignette for a couple weeks, at least, but happy to contribute something later in August if it's still needed then.
Currently, the how to section in the README is organized by
rrtools
function. However, there are several places where the appropriate function depends on the user's choice (e.g., which license to use), or where there are steps the user has to complete before running therrtools
function (e.g., when setting up version control).Does it make sense to instead organize this section around the concept each step represents (e.g., create the package, choose a license, use version control), listing any prerequisite steps, and then the function? One potential benefit is that this would help reinforce the key components of rr, particularly for people who are less familiar with them. The downside, of course, is that it requires a bit more effort to locate the appropriate function. Organizing things conceptually seems useful to me, but perhaps the current approach was intentional?
Happy to make a first attempt at this, if others are amenable.