Feedback on "Get Started" tutorials (tool: RStudio)

[FlorianPargent]

What would you like to do?

Give feedback or suggest an improvement

Description

In the last year, I have repeatedly taught PhD students Quarto using the Get started tutorials with RStudio. I have collected a list of problems that come up repeatedly when my students try to follow the tutorial. Perhaps this feedback might be of interest to you if you want to further improve these great tutorials!

Tutorial: Hello, Quarto

• It seems that for some students, Preview in viewer pane is not the default, even if they have just installed RStudio for the first time (I have not investigated why this could be the case). One could inform the reader in a footnote that if the preview does not automatically open on the right side in RStudio when they click Render, they should go to the gear wheel next to the Render button, select Preview in Viewer Pane and then click Render again.

• The tutorial mentions the Markdown syntax (e.g. **bold**) used in Quarto but never gives the reader this link where the Pandoc Markdown syntax is described in-depth.

Tutorial: Computations

• Many students when going through the tutorial copy code from the tutorial website into their own .qmd file in visual mode which breaks the markdown syntax and their .qmd file does not render anymore. We must often remind them: "Whenever you copy something from the tutorial website into your own .qmd document, always make sure that in RStudio you copy into Source mode instead of Visual mode. Otherwise, rendering the document will not work correctly because the visual mode adds some extra characters that brake the markdown syntax."

• Code Linking (code-link: true) requires installalling the R packages downlit and xml2, which is not mentioned directly in the tutorial. Many students fail to solve this problem on their own and waste a lot of time.

• The tutorial discusses yaml options (e.g. df-print: paged) on how to display Data Frames but does not actually print any data.frame in the .qmd document. We always tell our students that they can add the following chunk to test the different df-print options:

  library(palmerpenguins)
  penguins
  

• The section on Inline Code mentions that both the `{r} ` and `r ` syntax exists (and provides a link to the documentation). But the important difference that `r ` treats the output as markdown code while `{r} ` treats the output as ordinary text is not mentioned.

Tutorial: Authoring

• The tutorial claims that creating a new .qmd document through the RStudio menu will create an empty document, which does not seem to be true. From what I have seen, the "empty document" always contains the YAML-header

  ---
  title: "Untitled"
  format: html
  ---

• The tutorial claims that "the format choice (HTML) is not even reflected in the YAML as it is the default output format for Quarto documents" when creating a new .qmd document, which also does not seem to be true (see above).

• When you render the .qmd file as .docx by use of the Render button in RStudio for the first time, RStudio sometimes misleadings asks where to safe the file, even though the .docx file has already been silently created in the background.

• When you have used the Render button in RStudio to render .docx this might break the Viewer in RStudio (because RStudio seems to remember the last output format it has rendered and the Viewer does not work for .docx). One solution to fix this is to manually render once as .html or .pdf via the Render options, which should reactivate the Viewer.

• The tutorial wants the reader to add a reference to the equation labeled #eq-slr, but this reference is actually already included in the provided .qmd file.

• In the section on Cross References, the tutorial could make it more clear that cross-references must use the reserved keywords (fig-, tbl-, eq-, ...) in the respective labels and link to the cross-referencing documentation.

• Rendering the final authoring-complete.qmd file you can download at the end of the tutorial will only work, if you also have the references.bib file in the same folder. This file is not provided as a download, but is created automatically by RStudio when you inserted your first reference in the citations section of the tutorial. Some students who only read the tutorial and then try to render the final .qmd in the end are confused why it does not work (because they actually never created the .bib file).

[mcanouil]

Thanks for the feedback.

The section on Inline Code mentions that both the {r} and r syntax exists (and provides a link to the documentation). But the important difference that r treats the output as markdown code while {r} treats the output as ordinary text is not mentioned.

Someone else shared the same feedback.
I made a PR to fix this.

• docs: make bracketed inline code the default syntax quarto-web#1334

[mcanouil]

The tutorial claims that creating a new .qmd document through the RStudio menu will create an empty document, which does not seem to be true. From what I have seen, the "empty document" always contains the YAML-header

It is an "empty document" as it has no content and only has a YAML front matter (metadata), but it isn't an "empty file".

[mcanouil]

Code Linking (code-link: true) requires installalling the R packages downlit and xml2, which is not mentioned directly in the tutorial. Many students fail to solve this problem on their own and waste a lot of time.

In the section there is:

Note that code linking is currently implemented only for the knitr engine via the downlit package.