Quick start in README vs. workflow vignette

[sbfnk]

There is a fair amount of duplication between the quick start section in the README and the workflow vignette.

I wonder if there's a case for shortening the README to take out the code examples in the Quick start section and moving any of the bits that aren't in the vignette yet there (e.g. the paragraph on estimating delays), and instead pointing to the vignette.

[seabbs]

Do you know what current thinking is on having a readme quick start vs linking out to a vignette? I'm definitely open to the idea but we will need to make a very big effort to signpost users so they don't get lost.

[sbfnk]

I guess this? https://r-pkgs.org/other-markdown.html#sec-readme

1. A paragraph that describes the high-level purpose of the package.

2. An example that shows how to use the package to solve a simple problem.

3. Installation instructions, giving code that can be copied and pasted into R.

4. An overview that describes the main components of the package. For more complex packages, this will point to vignettes for more details. This is also a good place to describe how your package fits into the ecosystem of its target domain.

Which perhaps is what there is at the moment. Or perhaps the package doesn't solve any simple problems, which makes the whole thing more involved straight away (and links to point 4 above).

I'm really not particularly inclined one way or the other, just that looking at the using examples vs. specifying delays question I noticed how much we repeat the same examples across the package (which might be a good thing, just gets cumbersome when wanting to make changes).

[seabbs]

I think in general some repition of the core concepts is not that bad given how much of a struggle it is to get users to read the docs but if its a pain to keep everything in sync (which it is) I think it makes sense having one really good getting started vignette and very clearly directing people from the README to it. I've been thinking about doing this for epinowcast as it doesn't have just one getting started option (do you want Rt, a nowcast etc) and so the quick start is just a bit confusing (which is also true of EpiNow2.

[sbfnk]

One example I personally like is the rstanarm README.

Perhaps we could have something like:

• 1-2 paragraph high-level summary
• Arrows for:
  1. more detail
  2. models contained (estimate_infections, estimate_truncation, estimate_secondary, estimate_delay)
• Resources (links to vignettes including getting started)
• Installation
• Contributing

[seabbs]

Yes, that is a nice example. I like the proposed structure. Something I have wanted for a long time is as an automated section that lists contributors in the README but that can be addressed as its own issue/discussion.

[jamesmbaazam]

One example I personally like is the rstanarm README.

Perhaps we could have something like:

• 1-2 paragraph high-level summary

• Arrows for:

  1. more detail
  2. models contained (estimate_infections, estimate_truncation, estimate_secondary, estimate_delay)

• Resources (links to vignettes including getting started)

• Installation

• Contributing

You have my upvote. I've always thought the quick start section of the "README" could be moved to the "Getting Started" vignette because currently, the readme is quite long and intimidating.

[seabbs]

"Getting Started" vignette because currently, the readme is quite long and intimidating.

In some sense this just moves the problem as then the getting started vignette will be intimidating! Would be good to work on this though potentially it is just a little bit of an intimidating tool.

[jamesmbaazam]

In some sense this just moves the problem as then the getting started vignette will be intimidating!

I don't think so. I think it's more about how much information a NEW user is bombarded with when they land on the page. It's good to ease the user into the information you want to give them.

On the landing page, they'll see what the package does and with what functions, then they'll wonder, "how can I use function x then?" -> Getting started vignette

"Okay, that was easy but that's not how it works in real life. I usually have to do a lot of things before getting to this step" -> (workflow vignette)

"How do I connect these ideas?" -> case studies

[seabbs]

Fair enough. Have you seen any literature discussing this? Seems to hang on whether people clicking through things reduces the burden on them - which I imagine it probably does to some degree unless they can't find the things to click (which happens to a lot of users).

[jamesmbaazam]

This article has good references on the topic.

For example,

• Arguments for using hypertext format for presenting complex ideas

  • Hypertext Learning Environments, Cognitive Flexibility, and the Transfer of Complex Knowledge: An Empirical Investigation

• Arguments for using linear (non-hypertext) presentation versus non-linear (hypertext) presentation of complex ideas

  • The Effects of Hypertext on Reader Knowledge Representation

• In essence, it depends on the audience. "Experts" might not necessarily care about the order of presentation as much as "novices".

[seabbs]

Amazing! I'll give those a read.

[jamesmbaazam]

Enjoy. Very interesting literature.

[jamesmbaazam]

Makes me wonder if we might want to set up a small user survey via .onLoad() to find out more about the user community.

[seabbs]

Makes me wonder if we might want to set up a small user survey via

That is an interesting idea. data.table recently put out a survey though I am not sure about putting it in .onLoad() - feels a bit invasive?

[jamesmbaazam]

Oh, I just looked it up. I suggested .onLoad() because it's the closest to a user who doesn't interact with GitHub. I think the README would be a good place too. Not sure what the general practice is but could dig around if we think it's a good idea to carry it forward. Linking to the thread for the data.table survey here for future reference Rdatatable/data.table#5686.

[LizaHadley]

I like to be walked through new things :)

[jamesmbaazam]

I really like the change to the epinowcast README (dropdown arrows so cool 🤩 ) and "Getting Started" vignette here epinowcast/epinowcast#375.

Should I go ahead with this PR?

[jamesmbaazam]

@seabbs and @sbfnk

I'm working on this and have a few questions:

1. Should this PR just focus on moving things around then having follow-up PRs to remove the duplications between the the Getting Started vignette and estimate_infections() workflow vignette?
2. In the contributing section in the README, I would suggest we remove "Please note that due to operational constraints priority will be given to users informing government policy or offering methodological insights" and decide on this on a case-by-case basis when we get contributions as it might discourage new contributors.
3. Is this a good time to remove the reporting templates section as suggested by @seabbs here Reporting templates and the report package #495 (comment)?

[sbfnk]

I see you've answered (1) with yes which makes sense to me.

(2) I agree

(3) I think so, yes - though can be done in a follow-up PR to keep things clear/contained.

[jamesmbaazam]

though can be done in a follow-up PR to keep things clear/contained.

True.

[seabbs]

"Please note that due to operational constraints priority will be given to users informing government policy or offering methodological insights"

This is yet more legacy from when we were getting multiple support emails a day so can definitely go.