Onboarding issues: Documentation
Closed this issue · 3 comments
Make corrections or additions to documentation, either in-line or vignettes
- Error in max_char format example code
- Missing group in group_by example code
- Template not showing up in list
- Show example of skim_tee
Two comments/questions:
@jenniferthompson Do you mean and example of skim_tee in the in line code, the vignette, both? (I'm guessing both is good as I type this).
About having the template to show how to work with fonts ... the issue is complex, but if you try to include the examples in a vignette you are going to get a mess for Windows users and users of environments that don't support utf-8. Further using fonts usually will require installing extraFont which would mean if it is in a vignette that we have to force everyone to install it and then also possibly to install fonts. Although I did think @jimhester had good advice about adding some more detail to the vignette, I don't think it makes sense to put things that are not going to render correctly into the vignette. The one thing might be to put a small bit of sample code that would effectively test whether a user has an issue to deal with in terms of rendering. I've been trying to avoid images but maybe an image showing a "correct" rendering that could be compared with whatever they get when the vignettes are generated.
@elinw Regarding the skim_tee example - I added one in my PR for the vignette, so that (or something like it) may be enough! I don't think it needs a ton of space; it just took me a few reads to figure out when it could be useful.
I don't know enough about fonts (or Windows!) to have a great solution to the font question; I trust you that it's complicated. :) If it's feasible, I like the idea of a bit of sample code/image to check for likely problems that would be accessible to someone not that knowledgeable about fonts 🖐, and then the vignette could be a source for resources and troubleshooting if that code gives results that are different from what's expected.
@jenniferthompson
I added examples of skim_tee(), skim_to_wide() and skim_to_list() in the vignette too, I thought about it and I think it's helpful. skim_tee() was confusing to me too.
One of the issues with fonts is that your computer may produce histograms just fine if it is making a pdf but not if it is making a word document or HTML. So I think the vignette possibly should be expanded to focus on identifying problems and suggesting options.
I knew nothing at all about fonts in rmarkdown before this.
@elinw More examples sound awesome! Looking forward to checking them out.
Fonts can be so frustrating and I'd hate for that to be a barrier for folks to use such a great package. So I agree - expanding the vignette may be a lot of work, but it would be really helpful to users to learn from your newfound expertise!