User-friendliness of the pkgdown site home/main page vs. the "Get Started" page
asadow opened this issue · comments
I'm not sure where this post belongs. I assume here as the README by default becomes the main page, which I think is causing the tension described below.
With my spouse learning R, I've noticed she's ran into the same confusion I ran into years ago and thought it might be worth mentioning.
The confusion can be summed up as "Is this the overview/guiding/getting started page?"
Take rvest as an example. The main page has an Overview, Installation, and Usage section. Sounds like something you would read when getting started, no? But actually, there is a separate "Getting Started" page with more details. What can happen is that someone can get the impression that the main page is a guide, read it, but then feel lost while also feeling that they read the guide. Maybe something like a For More section at the bottom of the main page which directs readers to the Getting Started page would help.
googledrive takes a different approach, which I believe is more user-friendy. The Get Started page redirects readers to the main page or the articles. The README, which is not a full guide, does not de facto become the main page of the site. The index.Rmd, which is a fuller guide, becomes the pkgdown site main page.
I agree.
I'm not clear what you're advocating for. Improved pkgdown documentation around the most user friendly front pages?
Perhaps @jennybc could provide some insight on why the googledrive pkgdown site has a unique organization..
The googledrive approach is really a response to the ongoing battle to document an API-wrapping package that is released on CRAN. I think I wanted googledrive to have an actual vignette, meaning: something that shows up here:
https://cloud.r-project.org/web/packages/googledrive/index.html
But then I wanted that vignette to just point people to the real docs, that only live in the pkgdown site. Because to truly demonstrate how the package works, you need auth, which can't be done on CRAN.
Drawing inspiration from googledrive when developing an API-wrapping package, I figured that was your motivation for the organization @jennybc. I brought your package up more as an example of how someone would not get confused as to whether the main page or the Getting Started page is the go-to guide.
@jayhesselberth I'm not sure what solution to advocate for (yet). I just wanted to note a confusion that might be common for new readers.
The goal of the index page is to give a rough overview of the package without being too long (since the pkgdown design currently doesn't have a TOC on the homepage, and I don't see how to add one given the other content we already have in the sidebar). So I think the best we can do is add an obvious "learn more" link at the bottom of the readme. I've filed an issue to that effect in rvest: tidyverse/rvest#410. If there are other packages that you think would also benefit from that treatment, please let me know!