Elaborate information on collaborative projects

docs/_quarto.yml

@@ -45,7 +45,6 @@ format:
     theme:
       - cosmo
       - custom.scss
-    css: styles.css
     toc: true
 
 editor: visual

docs/configuration.qmd

@@ -27,7 +27,9 @@ default-exclude = true
 ## Configuration recommendations
 
 For collaborative projects, we recommend creating an `air.toml` and placing it at your project root even if you plan to use the default Air settings.
-This has a number of benefits:
+The easiest way to do this is by running [`usethis::use_air()`](https://usethis.r-lib.org/dev/reference/use_air.html) (note that this currently requires the development version of usethis).
+
+The existence of an `air.toml` has a number of benefits:
 
 -   It stops Air from using user level editor settings.
     When an `air.toml` is not present, Air respects some user level editor settings, such as `editor.tabWidth` in VS Code or Positron.
@@ -43,7 +45,7 @@ This has a number of benefits:
 If you do plan to just use the defaults, the `air.toml` can be completely empty.
 The important thing is that it exists.
 
-If you're happy with Air's defaults (or your IDE settings, see section on synchronization) and don't plan for your project to ever leave your computer, you likely don't need an `air.toml`.
+If you're happy with Air's defaults (or your IDE settings, see [synchronization](#configuration-settings-synchronization)) and don't plan for your project to ever leave your computer, you likely don't need an `air.toml`.
 
 ## Configuration discovery
 
@@ -259,4 +261,4 @@ igraph::graph_from_literal(A +-+ B +---+ C ++ D + E)
 ```
 
 In the short term, we also anticipate that this will be useful to avoid formatting of `tibble::tribble()` calls.
-In the long term, Air may have more sophisticated features for automatically formatting using a specified alignment.
+In the long term, Air may have more sophisticated features for automatically formatting using a specified alignment.

docs/editor-vscode.qmd

@@ -14,9 +14,29 @@ Air is available [as an Extension](https://marketplace.visualstudio.com/items?it
 The extension comes pre-bundled with an Air binary, so you don't need anything else to get going!
 The Air extension is hosted in the VS Code Marketplace and on OpenVSX.
 
+## User vs Workspace settings
+
+VS Code and Positron give you the ability to edit settings at a *user* level and at a *workspace* level (i.e. for just the current project you are working on).
+To enable some Air features, like [Format on Save](#editor-vs-code-format-on-save), you'll need to adjust settings in either your user or workspace level `settings.json` file.
+We generally recommend modifying workspace level settings for two reasons:
+
+-   Workspace level settings exist inside your workspace folder at `.vscode/settings.json` and are checked in to your version control system.
+    This means that your collaborators will get those settings automatically when they check out your project.
+    User level settings are not checked in to version control.
+
+-   User level settings are automatically applied for *all* projects that you open.
+    While this sounds nice, if you open an older project (or a project you don't own) that doesn't use Air, then you'll have to remember to turn off your user level Air settings before committing to that project, otherwise you may create a large amount of format related diffs that the project may not want.
+
+The easiest way to set up a workspace level `settings.json` with the recommended settings is by running [`usethis::use_air()`](https://usethis.r-lib.org/dev/reference/use_air.html) (note that this currently requires the development version of usethis).
+
+Alternatively, to open your `settings.json` file from the Command Palette (`Cmd + P` on Mac/Linux, `Ctrl + P` on Windows):
+
+-   Run `Preferences: Open Workspace Settings (JSON)` to modify workspace specific settings (recommended).
+-   Run `Preferences: Open User Settings (JSON)` to modify global user settings.
+
 # Features
 
-## Format on save
+## Format on save {#editor-vs-code-format-on-save}
 
 Once you have the extension installed, turn on Format on Save for R documents by opening your `settings.json` and adding:
 

docs/formatter.qmd

@@ -24,7 +24,7 @@ Formatters do not change the meaning of code; instead they ensure that whitespac
       geom_point()
     ```
 
-    As well as *expanded* (i.e. vertically laid out) function calls:
+    as well as *expanded* (i.e. vertically laid out) function calls:
 
     ``` r
     list(