Improve documentation in README. (#10)

* Improve documentation in README.

* PR feedback.

* Fix spelling mistake in README.

Author: Choc13

README.md

@@ -5,12 +5,20 @@
 [![NuGet version](https://img.shields.io/nuget/v/Winton.DomainModelling.AspNetCore.svg)](https://www.nuget.org/packages/Winton.DomainModelling.AspNetCore)
 [![NuGet version](https://img.shields.io/nuget/vpre/Winton.DomainModelling.AspNetCore.svg)](https://www.nuget.org/packages/Winton.DomainModelling.AspNetCore)
 
-Conventions useful for creating an ASP.NET Core based REST API on top of a domain model.
+Conventions useful for creating an ASP.NET Core based REST API on top of a domain model. Specifically, it provides extension methods which convert from domain model types, as defined in [`Winton.DomainModelling.Abstractions`](https://github.com/wintoncode/Winton.DomainModelling.Abstractions) to ASP.NET Core types.
 
 ## `Result` Extensions
 
-This library provides a `ToActionResult` extension method for `Result<TData>` which converts it to an appropriate `IActionResult`. 
-There are various overloads to provide flexibiility. 
+`Result<TData>` is a type defined in the `Winton.DomainModelling.Abstractions` package. 
+It is a type that is intended to be returned from domain operations.
+It allows operations to indicate both successes and failures to the client.
+In this case the client is an ASP.NET Core Controller.
+In a Controller, however, we need to return an `IActionResult` rather than a `Result<TData>`. We have two cases to consider:
+* If the `Result<TData>` was a success then we want to return a 2xx response from the API containing the data in the body.
+* If the `Result<TData>` was a failure then we want to return a 4xx response from the API containing [problem details](https://tools.ietf.org/html/rfc7807) in the body.
+
+This library provides a `ToActionResult` extension method for `Result<TData>` which matches on the result and converts it to an appropriate `IActionResult`.
+There are various overloads to provide flexibility. 
 It is expected that this will be used within an [`ApiController`](https://docs.microsoft.com/en-us/aspnet/core/web-api/?view=aspnetcore-2.2#annotation-with-apicontroller-attribute) so that ASP.NET Core will apply its REST API conventions to the `IActionResult`.
 
 ### Successful Result Mappings