diff --git a/README.md b/README.md
index f8e22f33..3ca7c4f8 100644
--- a/README.md
+++ b/README.md
@@ -62,6 +62,8 @@ This is a very simple example of the steps you would take to generate an install
    }
    ```
 
+If you're not sure how these instructions fit into your app, check the example apps for common scenarios such as WPF or Avalonia.
+
 ## Documentation
 - 📖 [Read the docs](docs)
 - 🕶️ [View example apps](examples)
diff --git a/examples/AvaloniaCrossPlat/readme.md b/examples/AvaloniaCrossPlat/readme.md
new file mode 100644
index 00000000..236fa49a
--- /dev/null
+++ b/examples/AvaloniaCrossPlat/readme.md
@@ -0,0 +1,40 @@
+# AvaloniaCrossPlat
+_Prerequisites: vpk command line tool installed_
+
+This app demonstrates how to use Avalonia to provide a desktop UI, installer, and updates for Mac, Linux, and Windows.
+
+You can run this sample by executing the build script with a version number (eg. `build-win.bat 1.0.0`).
+There are build scripts provided for each platform (`build-win.bat`, `build-linux.sh`, `build-osx.bat`).
+
+Once built, you can install the app - build more updates, and then test updates and so forth. The sample app will check the local release dir for new update packages. 
+
+In your production apps, you should deploy your updates to some kind of update server instead.
+
+On Linux, there is no installer, since the program is shipped as a `.AppImage`, it is only portable - however it can still update itself by replacing it's own `.AppImage` (even if that `.AppImage` is inside priveleged directories)
+
+## Avalonia Implementation Notes
+The Avalonia Template will generate a `Program.Main()` for you. You need to be careful when editing this file as to not break the Avalonia designer. You must not delete the `BuildAvaloniaApp()` function, but you must add the `VelopackApp` builder to the `Main()` method. For example:
+
+```cs
+class Program
+{
+    // Initialization code. Don't use any Avalonia, third-party APIs or any
+    // SynchronizationContext-reliant code before AppMain is called. 
+    // things aren't initialized yet and stuff might break.
+    [STAThread]
+    public static void Main(string[] args)
+    {
+        VelopackApp.Build().Run();
+        BuildAvaloniaApp().StartWithClassicDesktopLifetime(args);
+    }
+
+    // Avalonia configuration, don't remove method; also used by visual designer.
+    public static AppBuilder BuildAvaloniaApp()
+    {
+        return AppBuilder.Configure<App>()
+            .UsePlatformDetect()
+            .WithInterFont()
+            .LogToTrace();
+    }
+}
+```
\ No newline at end of file
diff --git a/examples/VeloWpfSample/readme.md b/examples/VeloWpfSample/readme.md
index 2e4d709d..a8277826 100644
--- a/examples/VeloWpfSample/readme.md
+++ b/examples/VeloWpfSample/readme.md
@@ -1,6 +1,8 @@
 # VeloWpfSample
 _Prerequisites: vpk command line tool installed_
 
+This app demonstrates how to use WPF to provide a desktop UI, installer, and updates for Windows only.
+
 You can run this sample by executing the build script with a version number: `build.bat 1.0.0`. Once built, you can install the app - build more updates, and then test updates and so forth. The sample app will check the local release dir for new update packages. 
 
 In your production apps, you should deploy your updates to some kind of update server instead.
diff --git a/examples/readme.md b/examples/readme.md
index 243fe2a7..fe96c8d7 100644
--- a/examples/readme.md
+++ b/examples/readme.md
@@ -1,5 +1,5 @@
 # Velopack Examples
 
-- [**AvaloniaCrossPlat**](AvaloniaCrossPlat) - this Example app uses Avalonia to provide a desktop UI for Mac and Windows. The provided build scripts (`build-win.bat` and `build-osx.sh`) will compile Velopack dependencies, so check that you've installed the [Velopack compiling prerequisites](../docs/compiling.md) before cloning this repository.
+- [**AvaloniaCrossPlat**](AvaloniaCrossPlat) - uses Avalonia to provide a desktop UI, installer, and updates for Mac, Linux, and Windows.
 
 - [**VeloWpfSample**](VeloWpfSample) - demonstrates how to use Velopack effectively with WPF.
\ No newline at end of file