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

Add an article about accessibility features #2108

Draft
wants to merge 5 commits into
base: main
Choose a base branch
from

Conversation

cderv
Copy link
Collaborator

@cderv cderv commented Apr 14, 2021

Preview: https://deploy-preview-2108--rmarkdown-pkg.netlify.app/articles/articles/accessibility

Note: I used the visual editor to format the Rmd post.

Issue: I don't know why yet but the toc is off with pkgdown... 🤔

Copy link
Member

@yihui yihui left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel this article should go to the R Markdown Cookbook---perhaps a section after this https://bookdown.org/yihui/rmarkdown-cookbook/html-accessibility.html (or add a subsection in it). I tend not to add more vignettes or articles into the package, but keep all documentation in the Definitive Guide or Cookbook. Same thing applies to bookdown and blogdown, since they all have companion books (unlike other packages). We can always link to a specific section in the books and promote it when necessary.

What do you think?

@cderv
Copy link
Collaborator Author

cderv commented Apr 14, 2021

This is a good question. I asked myself the same thing because I was worried of duplication and several places for documentations. So I understand your comment.

I feel this article should go to the R Markdown Cookbook

The R Markdown Cookbook could certainly be a good place for this as there is already the chapters on accessibility.

I tend not to add more vignettes or articles into the package, but keep all documentation in the Definitive Guide or Cookbook. Same thing applies to bookdown and blogdown, since they all have companion books (unlike other packages).

However, I feel package websites are a great way to document some specific topics and could be easier for "discoverability" than in the middle of a book. Unfortunately, we don't have a lot of vignette and so documentation inside package is sparsed. Even if vignettes could be a constraint (bc CRAN), 'articles' feature from pkgdown is nice to avoid that and still share documentations on websites.

So we should really discuss that and decide where new topics should be added. Current other ideas are:

All the other packages have useful documentations in their website - I feel we should have some too because it is expected by users and easily findable. Other packages don't have book though and we should also take advantage of that. Now that the books are promoted in front page, there is no way to miss it.

For this specific articles, I agree that a subsection in https://bookdown.org/yihui/rmarkdown-cookbook/html-accessibility.html maybe a better place for it. All the more because it shows how to use fig.alt which is in knitr really and this is not directly related to rmarkdown (except the fig_caption: FALSE)

I'll set this as a draft until we decide.

@cderv cderv marked this pull request as draft April 14, 2021 19:48
@yihui
Copy link
Member

yihui commented Apr 14, 2021

I need to go back to the pkgdown site discussion from a few months ago and think more about it. Basically, we have already got three resources for the documentation: the R help (Rd), the official website rmarkdown.rstudio.com, and the two 350-page books. I feel these were enough, and don't really want to invest too much into a fourth place for documentation (vignettes/articles). If there is anything new to add, I'd prefer adding to the existing resources. (BTW, the Lua filters vignette should perhaps go to Part IV of the Definitive Guide.)

@cderv
Copy link
Collaborator Author

cderv commented Apr 14, 2021

Yes we need to think this through.

BTW, the Lua filters vignette should perhaps go to Part IV of the Definitive Guide.

Yes I think so too. We mention them in the R Markdown Cookbook already too now : https://bookdown.org/yihui/rmarkdown-cookbook/lua-filters.html
This was after the vignette creation - at first it was mainly as a technical documentation about Lua filters but it should now get part of the book as there is interesting feature tied to it.

I need to make an habit of updating the books as new feature goes in.

@apreshill
Copy link
Contributor

Let's remove articles then? Distill does not have any either: https://pkgs.rstudio.com/distill/

@yihui
Copy link
Member

yihui commented Apr 14, 2021

That sounds good to me (after we move the Lua filters article into a book chapter or section).

@apreshill
Copy link
Contributor

It may be worth transitioning those book websites over to bs4_book so that online search works better, if that is the sole source of documentation.

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

Successfully merging this pull request may close these issues.

3 participants