Improved documentation, #7

README.md

@@ -6,12 +6,18 @@
 
 Taking screenshots of your app on every device and localisation quickly becomes time consuming. With two languages, four different iPhones and five screenshots you are faced with forty screenshots per release. If we increase the number of languages to 10 and add iPad support, this number explodes to 10 (languages) x 7 (devices) x 5 (screenshots) = **350 screenshots**!
 
-`Xnapshot` enables you to use C#, together with Xamarin.UITest, to automatically take the screenshots for you. Just derive from the abstract [Screenshots](https://github.com/Sankra/Xnapshot/blob/master/Xnapshot/Screenshots.cs) class, implement one method per screenshot and use your time productively while your computer takes the screenshots.
+`Xnapshot` enables you to use C#, together with Xamarin.UITest, to automatically take the screenshots for you. Just derive from the abstract [Screenshots](https://github.com/Sankra/Xnapshot/blob/master/Xnapshot/Screenshots.cs#L49) class, implement one method per screenshot and use your time productively while your computer takes the screenshots.
+
+## Complete working example
+
+Download this repository, open the solution in Visual Studio for Mac and run [Xnapshot.Example.Usage](https://github.com/Sankra/Xnapshot/blob/master/Xnapshot.Example.Usage/Program.cs) to see a working example. The solution contains the Xnapshot source, an iOS app to be screenshotted and the configuration of Xnapshot to actually take screenshots.
 
 ## Usage
 
-- Create an [awesome iOS app](https://itunes.apple.com/no/app/id953899091?at=11l5UV&ct=website) using C# and Xamarin.
-- Add the [Xamarin.TestCloud.Agent](https://www.nuget.org/packages/Xamarin.TestCloud.Agent/) nuget package to your iOS project and update your `AppDelegate` class to enable Calabash while running in debug mode.
+### Prerequisites
+
+- Create your [awesome iOS app](https://itunes.apple.com/no/app/id953899091?at=11l5UV&ct=website) using C# and Xamarin.
+- Add the [Xamarin.TestCloud.Agent](https://www.nuget.org/packages/Xamarin.TestCloud.Agent/) nuget package to your iOS project and update your `AppDelegate` class to enable [Calabash](https://github.com/calabash), the remote control for your app, while running in debug mode.
 
 ```cs
 public override void FinishedLaunching(UIApplication application) {
@@ -21,22 +27,30 @@ public override void FinishedLaunching(UIApplication application) {
 …
 ```
 
-- Add a new `Console project` to your solution and add the [Xnapshot](https://www.nuget.org/packages/Xnapshot/) nuget package.
-- Create a new class, `[AppName]Screenshots` and derive from the abstract [Xnapshot.Screenshots](https://github.com/Sankra/Xnapshot/blob/master/Xnapshot/Screenshots.cs#L56) class.
-- Add your preferred device type, iOS version, screenshots folder and path to your App bundle as constructor arguments. See [Usage](#usage) below for allowed values.
+### Configuration
+
+I use the settings for one of my own apps, [Golden Ratio Calculator](https://itunes.apple.com/no/app/id953899091?at=11l5UV&ct=website), to illustrate the usage of Xnapshot.
+
+- Add a new `Console project` to your solution and add the [Xnapshot](https://www.nuget.org/packages/Xnapshot/) nuget package. I name such projects `[AppName].Screenshots`.
+- Create a new class, `[AppName]Screenshots` and derive from the abstract [Xnapshot.Screenshots](https://github.com/Sankra/Xnapshot/blob/master/Xnapshot/Screenshots.cs#L49) class.
+- Add your iOS version, screenshots folder, path to your App bundle and devices you wish to screenshot as constructor arguments.
 
 ```cs
 public class GoldenRatioScreenshots : Screenshots {
   public GoldenRatioScreenshots() : base(
     DeviceType.iPhone,
-    "iOS-9-2", 
-    "/Users/sankra/Projects/GoldenRatioCalculator/screenshots/en-US", 
-    "/Users/sankra/Projects/GoldenRatioCalculator/iOS/bin/iPhoneSimulator/Debug/GoldenRatioCalculatoriOS.app") {
+    "iOS-12-2",
+    "/Users/sankra/Projects/GoldenRatioCalculator/screenshots/en-US",
+    "/Users/sankra/Projects/GoldenRatioCalculator/iOS/bin/iPhoneSimulator/Debug/GoldenRatioCalculatoriOS.app",
+    new[] {
+      "iPhone-SE",
+      "iPhone-XS"
+    }) {
   }
 }
 ```
 
-- It’s now time to implement the [SetAppStateForScreenshotX](https://github.com/Sankra/Xnapshot/blob/master/Xnapshot/Screenshots.cs#L124) methods. Use `Xamarin.UITest` to automate your [app](https://github.com/Sankra/Xnapshot/blob/master/Xnapshot/Screenshots.cs#L73), putting it in the correct state before each screenshot. The examples below are from my Golden Ratio Calculator app. `SetAppStateForScreenshot1` is empty because the first screenshot is of the first screen.
+- It’s now time to implement the [SetAppStateForScreenshotX](https://github.com/Sankra/Xnapshot/blob/master/Xnapshot/Screenshots.cs#L124) methods in `[AppName]Screenshots`. [Xamarin.UITest](https://docs.microsoft.com/en-us/appcenter/test-cloud/uitest/) is used to automate your [app](https://github.com/Sankra/Xnapshot/blob/master/Xnapshot.Example.Usage/ExampleScreenshots.cs#L24), putting it in the correct state before each screenshot. `SetAppStateForScreenshot1` is empty because the first screenshot is of the first screen.
 
 ```cs
 protected override void SetAppStateForScreenshot1() {
@@ -66,7 +80,7 @@ protected override void SetAppStateForScreenshot5() {
 }
 ```
 
-- Call the `TakeScreenshots()` method of your class and run your console app to take the screenshots.
+- Add the `TakeScreenshots()` method of your class to [Program.cs](https://github.com/Sankra/Xnapshot/blob/master/Xnapshot.Example.Usage/Program.cs#L7) and run your console app to take the screenshots.
 
 ```cs
 public static void Main(string[] args) {
@@ -77,19 +91,26 @@ public static void Main(string[] args) {
 }
 ```
 
-The screenshots look like this after this example app has run:
+My screenshots look like this after this example app has run:
 
-<h3></h3>
 <img src="https://hjerpbakk.com/img/Xnapshot/2example_screenshots_small.png" alt="example_screenshots_small" width="651.0" height="239.5">
 
 And the screenshots folder contains screenshots for all configured devices:
 
-<h3></h3>
 <img src="https://hjerpbakk.com/img/Xnapshot/0example_screenshots_folder.png" alt="example_screenshots_folder" width="676.0" height="456.0">
 
 ## Advanced Options
 
-The abstract [Screenshots](https://github.com/Sankra/Xnapshot/blob/master/Xnapshot/Screenshots.cs) class has a couple of advanced options that can be set in your `[AppName]Screenshots` constructor.
+The abstract [Screenshots](https://github.com/Sankra/Xnapshot/blob/master/Xnapshot/Screenshots.cs) class has a couple of advanced options that can be optionally set in your `[AppName]Screenshots` constructor:
+
+```cs
+public class ExampleScreenshots : Screenshots {
+  public ExampleScreenshots() : base(/*removed for brevity*/) {
+    SaveScreenshots = true;
+    OptimizeImagesAfterSave = false;
+  }
+}
+```
 
 ### [SaveScreenshots](https://github.com/Sankra/Xnapshot/blob/master/Xnapshot.Example.Usage/ExampleScreenshots.cs#L18)