Move some FAQs to Concepts

docs/concepts.md

@@ -8,6 +8,40 @@ description: Concepts used in Shorebird's code push product
 
 An explanation of the concepts used in Shorebird's code push product.
 
+## Code Push
+
+Code push, also referred to as "over the air updates" (OTA) is a cloud service
+enabling Flutter developers to deploy updates to their apps in production.
+Shorebird currently works on Android and iOS (alpha) and will eventually work
+everywhere Flutter works.
+
+"Code Push" is a reference to the name of a deploy feature used by the React
+Native community from [Microsoft](https://appcenter.ms) and
+[Expo](https://expo.dev), neither of which support Flutter.
+
+## Patching
+
+Patching is the process of updating an application's code without requiring the
+user to download a new version from the App Store or Play Store. This is done by
+creating a patch, which is a set of changes to the application's code that can
+be applied over-the-air.
+
+### What types of changes can be included in a patch?
+
+Patches can change any Dart code in your application. This includes:
+
+- App code
+- Generated code
+- Dependencies in `pubspec.yaml`, as long as they don't include native code
+  changes.
+
+This does **not** include:
+
+- Asset files (images, fonts, etc.), although we have plans to support this in
+  the near future (see https://github.com/shorebirdtech/shorebird/issues/318).
+- Native code (e.g. Java/Kotlin on Android or Objective-C/Swift on iOS).
+- Flutter engine changes (i.e., changes the Flutter version of your app).
+
 ## Glossary
 
 ### Application

docs/faq.md

@@ -7,17 +7,6 @@ description: Frequently asked questions.
 If you have questions not answered here, please ask! Both filing an issue
 or asking on [Discord](https://discord.gg/shorebird)) work.
 
-### What is "code push"?
-
-Code push, also referred to as "over the air updates" (OTA) is a cloud service
-enabling Flutter developers to deploy updates to their apps in production.
-Shorebird currently works on Android and iOS (alpha) and will eventually work
-everywhere Flutter works.
-
-"Code Push" is a reference to the name of a deploy feature used by the React
-Native community from [Microsoft](https://appcenter.ms) and
-[Expo](https://expo.dev), neither of which support Flutter.
-
 ### What is the difference between a patch and a release?
 
 We use the term "release" to mean preparing a binary for the app stores. In
@@ -196,8 +185,9 @@ for you, please let us know!
 ### Does code push work with large applications?
 
 Yes. There is no limit on the size of the application that can be patched with
-code push. As noted [below](#what-types-of-changes-does-shorebird-code-push-support),
-Shorebird can change any Dart code in your application no matter of size.
+code push. As noted in
+[Concepts](concepts#what-types-of-changes-can-be-included-in-a-patch), Shorebird
+can change any Dart code in your application no matter of size.
 
 ### What can I use Shorebird code push for?
 
@@ -271,22 +261,6 @@ production. We will use a variety of different techniques to make this possible
 depending on the platform. Current demos execute ahead-of-time compiled Dart
 code and do not require a JIT Dart compiler.
 
-### What types of changes does Shorebird code push support?
-
-Shorebird can change any Dart code in your application. This includes app code
-and generated code. You can also update dependencies in `pubspec.yaml` as long
-as they don't require native code changes.
-
-We have plans to support changing Flutter asset files (from pubspec.yaml) in the
-near future: https://github.com/shorebirdtech/shorebird/issues/318
-
-We do not have plans to support changing native code (e.g. Java/Kotlin on
-Android or Objective-C/Swift on iOS), and the tool will warn you if it detects
-that you have changed native code as it will not be included in the patch.
-
-Shorebird also cannot change your app's Flutter version in a patch, as the
-Flutter engine is native code.
-
 ### Does Shorebird support Flutter Web?
 
 Code push isn't needed for Flutter web. When a user opens a web app it downloads

docs/update-strategies.md

@@ -82,8 +82,7 @@ necessary patch and _not_ then prompt them to update.
 Shorebird patches are typically much smaller than full app downloads (a few KB
 on Android, a few hundred KB on iOS), so it is likely better for your users if
 you can use Shorebird to deliver patches instead of `in_app_update`. However,
-there are [changes which Shorebird cannot
-make](faq#what-types-of-changes-does-shorebird-code-push-support), so
+there are [changes which Shorebird cannot make](concepts#what-types-of-changes-can-be-included-in-a-patch), so
 `in_app_update` may be the best solution in some cases.
 
 Shorebird "patches" also do not change the version number of your app, so