New doc for formatting philosophy

Author: znorman-harris

extension/docs/.vitepress/sidebars/code-comments.sidebar.ts

@@ -38,6 +38,7 @@ export const CODE_COMMENTS_SIDEBAR: SidebarEntry[] = [
   },
   {
     text: 'Formatting',
+    link: '/code-comments/formatting',
     items: FORMATTING_SIDEBAR,
   },
 ];

extension/docs/code-comments/formatting.md

@@ -0,0 +1,19 @@
+# Formatting
+
+::: info
+
+For those new to formatting their IDL code, we have several resources for you to learn how the different options work.
+
+See [Configuration](/code-comments/formatting/configuration.md) and [Setup](/code-comments/formatting/setup.md) for more information.
+
+:::
+
+## Background and Design
+
+The goal of adding in formatting to our VSCode extension was to get to a place where developers have automated tooling to help them, and others, write consistent code.
+
+While we have some options to help fine-tune the visual appearance (i.e. "style" of your code), the spacing and more mechanical display is going to be the same for every user.
+
+As-is, we have some options that provide a balance with legacy controls you had in the IDL Workbench, but we likely won't add any more controls unless there are new language-level features that get added.
+
+If you want to learn more about the spirit of our decision, check out the [design philosophy of Prettier](https://prettier.io/docs/en/option-philosophy), which we modeled the IDL formatting after.