A first reading path
This path is a deliberately short reading list. Its aim is not to make you fluent in R or expert in Quarto. It gets the three pieces—R, an editor and Quarto—into the right conceptual order, then points you to the maintained lessons that teach their use. If you prefer, R can be replaced by Python or Julia.
Follow the routes in this chapter in order. Stop after the Quarto route if that is enough for now; project structure, Git and citations become useful when the first document turns into continuing research.
Need: establish the working environment
Why it matters. R performs the computation, Quarto turns structured source into a reader-facing output, and an editor gives you a place to work with both. Confusing the R console, a saved source file and a terminal makes every later instruction harder to interpret.
Read in this order. Install R from the Comprehensive R Archive Network. Follow Quarto’s Get Started page for the current Quarto installation and editor integration. Choose either Positron or RStudio Desktop and use that editor’s own introductory material; learning two interfaces at once adds little value.
You have enough when. You can identify the R console, a saved .R or .qmd source file and the terminal, and you know which application is responsible for computation, authoring and rendering.
Leave until later. Ignore Python, Julia, TeX, containers and editor customisation unless the first document actually requires them.
Need: get comfortable writing in plain text
Why it matters. If you are used to MS Word, the editable source may initially look unfinished: headings are marked with #, emphasis with * and links with brackets and parentheses. Quarto applies the visual formatting when it renders the document. This separation between source and output is a change of habit, not a difficult new language.
Read in this order. Spend five minutes with Markdown basics. Learn only enough to write a heading, a paragraph, a list, emphasis and a link. Put them in a .qmd file and render it. Keep the source and output beside each other while you make a few changes.
Expect the markup to feel conspicuous at first. Continue using it for a few days before deciding whether it is difficult; with ordinary use, you begin to read the structure rather than the marks.
You have enough when. You can make a small change in the source, render it and recognise the corresponding change in the output. You do not need to have memorised the syntax or to feel completely at home with it.
Leave until later. Tables, fenced divs, raw HTML or LaTeX, custom styling and other advanced Markdown features can wait until a document requires them.
Need: begin learning enough R to understand an analysis
Why it matters. Quarto can keep computation beside prose, but it does not remove the need to understand the computation. A researcher should be able to trace where data enter, what transformations occur and which object supplies a reported result.
Read in this order. Use R for Data Science (2e). Begin with Data visualization and Workflow: basics for an early visible result and the basic expression–assignment distinction. Continue to Data transformation and Data tidying. Read Workflow: scripts and projects when you are ready to move useful work out of console history and into saved source.
Run and change the examples while reading. The point is not to remember a catalogue of functions, but to learn how to inspect an object, read a sequence from top to bottom and check an intermediate result.
You have enough when. You can read a short analysis, identify its input data and derived objects, explain a transformation in ordinary language and make one controlled change while checking its effect.
Leave until later. Functions, iteration, package development and advanced modelling do not need to precede the first integrated document. Return to them when repetition or the scientific method requires them.
Need: create an integrated document
Why it matters. In a manual workflow, explanation, copied results and the computation that produced them can drift apart. A Quarto source can keep prose, citations, code and generated results close enough to change together (Knuth 1984).
Read in this order. First browse the Quarto Gallery so that the destination is visible before the syntax. Complete the relevant editor path in Get Started. Keep Markdown basics open while learning headings, lists, links, images and code blocks. Then read Using R to understand executable cells and their options. Finish with the authoring tutorial sections on document components and multiple output formats.
Use Quarto’s official pages as your primary source for this exercise, since they are maintained alongside the software.
Then let the document carry judgement as well as computation. Pick the most consequential analytical decision in your first document and record it beside the code, using the five-part decision record—choice, reason, timing, alternatives, consequence—from Keeping inferential judgement visible. This is the step that makes an integrated document more than just a prettier script.
You have enough when. You understand the difference between editable source and disposable output, have completed one official first-document exercise, can change the prose or analysis and regenerate the result, and have recorded one consequential decision beside the code that implements it.
Leave until later. Do not begin with journal templates, custom themes, extensions, PDF engines, dashboards or publishing services. The destination routes return to those when a reader, collaborator or venue creates the need.
The next route begins when the document is no longer a one-off exercise and needs to become a project you can leave and return to.
Next: A project you can return to.