Add more docs around migration from RStudio

.github/styles/config/vocabularies/posit-docs/accept.txt

@@ -41,4 +41,7 @@ Action Bar
 Action Bars
 Top Action Bar
 Jupyter Notebooks
+Air
+R
 Variables Pane
+Command Palette

_quarto.yml

@@ -89,9 +89,12 @@ website:
           href: migrate-vscode.qmd
         - section: "Migrating from RStudio"
           contents:
-          - rstudio-keybindings.qmd
-          - rstudio-rproj-file.qmd
-          - r-snippets.qmd
+          - migrate-rstudio.qmd
+          - migrate-rstudio-keybindings.qmd
+          - migrate-rstudio-settings-and-extensions.qmd
+          - migrate-rstudio-code.qmd
+          - migrate-rstudio-rproj.qmd
+          - migrate-rstudio-compare.qmd
         - git.qmd
     - title: "Help"
       style: "docked"

faqs.qmd

@@ -39,11 +39,11 @@ title: "Frequently Asked Questions"
   * RStudio has deeper support for Sweave and R Markdown compared to our targeted focus on Quarto in Positron, although Positron does support rendering R Markdown documents as well.    
   * Positron does not have inline output for source `.qmd` or `.Rmd` documents at this time, and Quarto or R Markdown documents will make use of the console and plot pane for execution/output. However, we are actively enhancing our Positron-native notebook UI that will provide inline outputs for R or Python sessions. Separately, we are also actively working on improving Quarto's Visual Editor to improve the authoring experience for Quarto. 
   * RStudio is extensible only via RStudio add-ins, and while Positron supports some of the same, existing RStudio add-ins, not all are supported. Rather than doubling down on the more limited RStudio add-in capabilities for novel integrations, we suggest exploring [extension development and our Positron API endpoints](extension-development.qmd).    
-  * We do _not_ plan to have a `.Rproj` equivalent for Positron (e.g. a `.positronproj`), but rather Positron can open and treat any folder as a "project" or workspace. We still suggest project-oriented workflows, and for more context, please see: [Migrating from RStudio: The Rproj File](rstudio-rproj-file.qmd).    
+  * We do _not_ plan to have a `.Rproj` equivalent for Positron (e.g. a `.positronproj`), but rather Positron can open and treat any folder as a "project" or workspace. We still suggest project-oriented workflows, and for more context, please see: [Migrating from RStudio: The Rproj File](migrate-rstudio-rproj.qmd).    
 
 ### I'm coming from RStudio, and Positron's keybindings are too different
 
-* Check out the [RStudio Keymap](keyboard-shortcuts.qmd#rstudio-keymap) section of our documentation.
+* Check out the [RStudio Keybindings](migrate-rstudio-keybindings.qmd) section of our documentation.
 * To opt in to these RStudio-like keybindings, enable the [`workbench.keybindings.rstudioKeybindings` setting](positron://settings/workbench.keybindings.rstudioKeybindings).
 
 ### How can I use Positron in an educational setting?

git.qmd

@@ -91,6 +91,7 @@ Positron provides a 3-way merge editor to help you resolve conflicts by choosing
 **Learn more:** [Merge conflicts in VS Code](https://code.visualstudio.com/docs/sourcecontrol/overview#_merge-conflicts)
 
 ## Integration with Git platforms
+
 Positron includes the [GitHub](https://open-vsx.org/extension/vscode/github) and [GitHub Pull Requests and Issues](https://open-vsx.org/extension/GitHub/vscode-pull-request-github) extensions out of the box, which let you manage GitHub repositories, issues, and PRs directly from within Positron. You can learn more about the extensions that Positron automatically installs for you on the [Extensions](extensions.qmd#bootstrapped-extensions) page.
 
 Other platforms are not integrated by default, but similar features are available after installing extensions like [GitLab Workflow](https://open-vsx.org/extension/GitLab/gitlab-workflow) or [Atlassian: Jira & Bitbucket](https://open-vsx.org/extension/atlassian/atlascode). You can search in the [Extensions pane](extensions.qmd#accessing-extensions) to find other extensions for the Git platform you use.

keyboard-shortcuts.qmd

@@ -27,19 +27,21 @@ Our documentation shows you keyboard shortcuts based on your operating system. F
 | -------- | ----------- |
 | {{< kbd mac=Command-Shift-M win=Ctrl-Shift-M linux=Ctrl-Shift-M >}} | Insert the pipe operator (<code>&#124;></code> or `%>%`) | 
 | {{< kbd mac=Option-- win=Alt-- linux=Alt-- >}} | Insert the assignment operator (`<-`) |
-| {{< kbd mac=Command-Shift-L win=Ctrl-Shift-L linux=Ctrl-Shift-L >}} | Load the current R package, if any | 
+| {{< kbd mac=Command-Shift-Enter win=Ctrl-Shift-Enter linux=Ctrl-Shift-Enter >}} | `source()` the current R script |
+| {{< kbd mac=Command-K win=Ctrl-K linux=Ctrl-K >}}, {{< kbd H >}} | Insert section |
+| {{< kbd mac=Command-Shift-L win=Ctrl-Shift-L linux=Ctrl-Shift-L >}} | Load the current R package, if any, with `devtools::load_all()` | 
 | {{< kbd mac=Command-Shift-B win=Ctrl-Shift-B linux=Ctrl-Shift-B >}} | Build and install the current R package, if any | 
 | {{< kbd mac=Command-Shift-T win=Ctrl-Shift-T linux=Ctrl-Shift-T >}} | Test the current R package, if any | 
 | {{< kbd mac=Command-Shift-E win=Ctrl-Shift-E linux=Ctrl-Shift-E >}} | Check the current R package, if any | 
 | {{< kbd mac=Command-Shift-D win=Ctrl-Shift-D linux=Ctrl-Shift-D >}} | Document the current R package, if any | 
 
-## RStudio keybindings
-
-If you'd prefer to use RStudio keybindings, see [our instructions](rstudio-keybindings.qmd) on how to enable them for Positron.
+:::{.callout-note}
+If you'd prefer to use RStudio keybindings, learn [how to enable them](migrate-rstudio-keybindings.qmd) in Positron.
+:::
 
 ## Custom shortcuts
 
-Because Positron is built on top of VS Code, you can use [its infrastructure for defining custom keybindings](https://code.visualstudio.com/docs/getstarted/keybindings). You can use this infrastructure with any Positron-specific commands, such as `workbench.action.executeCode.console` or `workbench.action.executeCode.silently`. 
+Because Positron is built on top of VS Code, you can use [its infrastructure for defining custom keybindings](https://code.visualstudio.com/docs/getstarted/keybindings). You can use this infrastructure with any Positron-specific commands, such as `workbench.action.executeCode.console` or `workbench.action.executeCode.silently`.
 
 As a specific example, you could add the following to your user `keybindings.json` (access this file from the Command Palette with *Open Keyboard Shortcuts (JSON)*) to make a keyboard shortcut to create a reprex from your current selection:
 
@@ -56,6 +58,15 @@ As a specific example, you could add the following to your user `keybindings.jso
 }
 ```
 
+## Troubleshooting
+
+If you are puzzled by the behaviour of a keyboard shortcut, here are two issues to consider:
+
+* **Context:** Many keyboard shortcuts are only enabled in certain contexts, such as when editing code or when working in an R package. Consider if you might be invoking the shortcut in an unexpected and unsupported context.
+* **Conflicts:** A keyboard shortcut can have multiple associations across different situations or extensions. When a shortcut is associated with more than one command, a priority system determines which command wins and the result might not be what you expect.
+
+The command _Preferences: Open Keyboard Shortcuts_ opens [an interface](https://code.visualstudio.com/docs/configure/keybindings) that is a great way to investigate keyboard shortcut mysteries.
+
 Be aware that Positron's integrated terminal can [intercept some keyboard shortcuts](https://code.visualstudio.com/docs/terminal/advanced#_keyboard-shortcuts-and-the-shell). You can set up a keybinding to skip the shell by specifying its command in the [`terminal.integrated.commandsToSkipShell` setting](positron://settings/terminal.integrated.commandsToSkipShell), either via the settings UI or by editing `settings.json`:
 
 ```json
@@ -65,4 +76,4 @@ Be aware that Positron's integrated terminal can [intercept some keyboard shortc
         "workbench.action.positronConsole.focusConsole"
     ]
 }
-```
+```

r-snippets.qmd → migrate-rstudio-code.qmd

@@ -1,7 +1,85 @@
 ---
-title: "Snippets for R"
+title: "Writing R code"
+aliases:
+  - r-snippets.qmd
 ---
 
+Writing R code in Positron should feel quite familiar to RStudio users.
+However two aspects of the workflow might feel a bit different:
+
+* [Formatting via Air](#formatting-r-code-with-air)
+* [Snippets](#r-snippets), both built-in and custom
+
+## Formatting R code with Air
+
+Positron can format R code with [Air](https://posit-dev.github.io/air/), a new R formatter whose creation was largely motivated by Positron.
+
+A formatter takes charge of the layout of your R code, which refers to whitespace, newlines, indentation, and the like.
+The goal is to enforce a set of style conventions that enhance readability and robustness.
+Air shares properties with other modern formatters and linters, such as Ruff for Python:
+
+* It's highly opinionated and offers relatively few options for customization.
+* It's written in Rust, which makes it extremely fast.
+
+### How do I install Air?
+
+Air is a command line tool which automatically ships with Positron.
+Most Positron users do not need to do anything intentional to install Air or to keep it up-to-date.
+
+Under the hood, Air is packaged in a VS Code extension, included in Positron as a [bootstrapped extension](extensions.qmd#bootstrapped-extensions) that is installed for you.
+The Air extension is published on [Open VSX](https://open-vsx.org/extension/posit/air-vscode), the marketplace used by IDEs like Positron and Cursor, and also on the [Visual Studio Code Marketplace](https://marketplace.visualstudio.com/items?itemName=Posit.air-vscode), which serves only the proprietary Microsoft builds of Visual Studio Code.
+
+### How do I use Air?
+
+There are various explicit and implicit gestures to run Air over your R code:
+
+* "Format on save": formats R code every time you save a file. This is a lifestyle you must opt in to, but it is our strong recommendation that you do so. Below we give details on how to set this up.
+* Formatting commands: These are explicit gestures to format specific bits of code.
+  - *Format Selection*
+  - *Format Document*
+  - *Quarto: Format Cell*
+  - *Air: Format Workspace Folder*
+
+  These are all available in the command palette.
+
+All R code receives some basic formatting as you type, but this first pass is focused only on indentation.
+A second formatting pass with Air, when you save the file or intentionally format it, produces a much better result, since Air works off of an actual syntax tree.
+
+:::{.callout-tip}
+You can use special comments to tell Air to [skip formatting specific sections of code](https://posit-dev.github.io/air/formatter.html#skip-comments), if you don't want to apply Air's strict formatting rules in a specific situation.
+:::
+
+### Opt in to "Format on save"
+
+The easiest way to get our recommended set up is to run [`usethis::use_air()`](https://usethis.r-lib.org/dev/reference/use_air.html) (note that this currently requires the development version of usethis).
+`use_air()` configures "Format on save" in the current workspace by modifying (or creating, if necessary) the `.vscode/settings.json` file.
+It also creates an `air.toml` file.
+
+VS Code and Positron let you customize settings at the user level and at the workspace level (i.e. for just the current project you are working on).
+We think "Format on save" makes the most sense to configure at the workspace level:
+
+* Workspace settings are recorded inside the workspace at `.vscode/settings.json`, allowing them to be tracked in version control. This means that all collaborators get those settings automatically when they check out the project, enforcing a common formatting style.
+* User level settings apply to any workspaces that you open. This sounds nice in theory, but you might not want automatic Air formatting in older projects or in projects that you don't own. If you opt in at the user level, you'll have to turn Air off somehow in these projects or risk creating a huge number of formatting diffs, when that's probably not your intent.
+
+Here is what `.vscode/settings.json` might look like for someone who wants their R code formatted on save, in both R scripts and Quarto documents:
+
+```json
+{
+    "[r]": {
+        "editor.formatOnSave": true,
+        "editor.defaultFormatter": "Posit.air-vscode"
+    },
+    "[quarto]": {
+        "editor.formatOnSave": true,
+        "editor.defaultFormatter": "quarto.quarto"
+    }
+}
+```
+
+To learn more about using Air, read its documentation for [Positron and VS Code](https://posit-dev.github.io/air/editor-vscode.html).
+
+## R snippets
+
 Code snippets let you insert ready-made templates for common coding patterns.
 For example, `for` is a reserved word in R that is used to create a loop.
 In actual usage, `for` is always part of a larger construct:
@@ -16,15 +94,15 @@ A snippet for `for` inserts this whole skeleton, with special placeholders that
 
 ![Completion list after typing "for", showing the snippet that can be inserted](images/snippets-for-example){width=700}
 
-It is common for IDEs to provide explicit support for code snippets and this certainly holds true for RStudio and Positron.
-This guide is intended to help users who have used snippets in RStudio adapt their approach for Positron, which inherits snippet behaviour from its VS Code roots.
+It is common for IDEs to provide explicit support for code snippets and this certainly holds true for both RStudio and Positron.
+This guide is intended to help users who have used snippets in RStudio adapt their approach for Positron, which inherits snippet behavior from its Code OSS architecture.
 
 Documentation on snippets in:
 
 * [RStudio](https://docs.posit.co/ide/user/ide/guide/productivity/snippets.html)
 * [VS Code](https://code.visualstudio.com/docs/editing/userdefinedsnippets)
 
-## Default and custom snippets in RStudio
+### Default and custom snippets in RStudio
 
 RStudio ships with a default set of snippets.
 For our purposes, it's useful to break them into two broad classes:
@@ -37,7 +115,7 @@ Under the hood, this initializes a user-level snippet file that is pre-populated
 You can then apply your desired changes, such as adding or deleting snippets.
 Going forward, this user-level file powers all of your RStudio snippets, i.e. there is no combining of built-in and user-level snippets.
 
-## Default and custom snippets in Positron
+### Default and custom snippets in Positron
 
 The completion experience in Positron arises from two components working together:
 
@@ -49,14 +127,14 @@ The completion experience in Positron arises from two components working togethe
 
 This division of labor means that the completion and snippet responsibilities are a bit different in Positron than in RStudio.
 
-### Reserved words
+#### Reserved words
 
 In Positron, the completion items related to R's reserved words are built into ark.
 Each reserved word can be completed on its own and, in some cases, as part of a larger snippet.
 
 ![Completion list with rectangles highlighting two entries for the `function` reserved word, one as a bare keyword completion and another as a snippet](images/snippets-keyword-with-two-items.png){width=700}
 
-### Everything else
+#### Everything else
 
 If you want snippets beyond those provided for R's reserved words, you'll need to configure that for yourself.
 Press {{< kbd mac=Command-Shift-P win=Ctrl-Shift-P linux=Ctrl-Shift-P >}} to open the command palette and type *Snippets: Configure Snippets*.

migrate-rstudio-compare.qmd

@@ -0,0 +1,45 @@
+---
+title: "Comparing RStudio and Positron Features"
+---
+
+## What is happening to RStudio?
+
+Be assured that RStudio is **not going away**.
+RStudio is stable and actively supported, and there is no timeline to deprecate it.
+That being said, RStudio and Positron are at very different points in their respective lifecycles, which is relevant when making decisions about adoption.
+Positron is under much more active development, with a rapidly expanding set of features.
+RStudio's development, on the other hand, is much more focused on bug fixes and product stability.
+
+## Features unique to RStudio
+
+Some features are present in RStudio, but not in Positron as of today.
+Some of these features may eventually come to Positron, but if any of these are dealbreakers for you, that is a reason for you to stick with RStudio.
+
+* Inline output in Quarto documents, i.e. a notebook-style interface for `.qmd` (or `.Rmd`) files. Follow along for updates on this feature request in <https://github.com/posit-dev/positron/issues/5640>.
+* Saving and reloading workspace state when you restart R.
+* Dedicated panes and buttons for specialized tasks, such code profiling or installing or developing packages.
+* History pane. Follow along for updates on this feature request in <https://github.com/posit-dev/positron/issues/5484>.
+* Data import widget. Follow along for updates on this feature request in <https://github.com/posit-dev/positron/issues/5515>.
+* RStudio add-ins. Follow along for updates on this feature request in <https://github.com/posit-dev/positron/issues/1313>.
+
+## Features unique to Positron
+
+Some features are available in Positron, but not in RStudio.
+If any of these features are very appealing to you, that is a reason to move some or perhaps all of your work to Positron.
+
+* Easy access to [multiple R versions](r-installations.qmd) and [multiple concurrent R sessions](managing-interpreters.qmd).
+* An [integrated AI assistant](assistant.qmd) that can "see" and, optionally, execute code in your active R (or Python) sessions, among many other capabilities.
+* Python as a first-class citizen, with support for data science workflows that is on par with R.
+* Support for other languages beyond R and Python, via built-in language intelligence or extensions.
+* An integrated [Data Explorer](data-explorer.qmd) for dataframes in your active R (or Python) sessions and for a variety data files (CSV, Parquet, etc.).
+* Extensibility via a large marketplace of 3rd party [extensions](extensions.qmd).
+* [Remote sessions](remote-ssh.qmd), i.e. where the user interface is local but the compute is elsewhere.
+
+
+::: {.callout-tip}
+It's worth pointing out that using Positron is not an all-or-nothing decision.
+It is entirely reasonable to use Positron in some projects and RStudio in others.
+Likewise, within a specific project, some tasks might feel easier in Positron and others in RStudio.
+There is nothing irreversible or exclusive about interacting with the files that constitute a project from one IDE versus another.
+:::
+