Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

User-friendliness of the pkgdown site home/main page vs. the "Get Started" page #2372

Closed
asadow opened this issue Nov 17, 2023 · 5 comments
Closed

Comments

@asadow
Copy link

asadow commented Nov 17, 2023

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.

@asadow asadow changed the title User-Friendliness of the pkgdown site home/main page vs. the "Get Started" page User-friendliness of the pkgdown site home/main page vs. the "Get Started" page Nov 17, 2023
@wendyhb
Copy link

wendyhb commented Nov 17, 2023

I agree.

@jayhesselberth
Copy link
Collaborator

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..

@jennybc
Copy link
Member

jennybc commented Nov 29, 2023

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.

@asadow
Copy link
Author

asadow commented Nov 30, 2023

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.

@hadley
Copy link
Member

hadley commented Apr 11, 2024

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!

@hadley hadley closed this as completed Apr 11, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

5 participants