📚 Improve README

README.md

@@ -1,31 +1,87 @@
-# PleOps Cake recipe: a simple DevOps workflow [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat)](https://choosealicense.com/licenses/mit/) ![Build and release](https://github.com/pleonex/PleOps.Cake/workflows/Build%20and%20release/badge.svg?branch=main&event=push)
+# PleOps Cake ![logo](./docs/images/logo_48.png)
+
+<!-- markdownlint-disable MD033 -->
+<p align="center">
+  <a href="https://www.nuget.org/packages/Cake.Frosting.PleOps.Recipe">
+    <img alt="Stable version" src="https://img.shields.io/nuget/v/Cake.Frosting.PleOps.Recipe?label=nuget.org&logo=nuget" />
+  </a>
+  &nbsp;
+  <a href="https://dev.azure.com/benito356/NetDevOpsTest/_packaging?_a=feed&feed=PleOps">
+    <img alt="GitHub commits since latest release (by SemVer)" src="https://img.shields.io/github/commits-since/pleonex/PleOps.Cake/latest?sort=semver" />
+  </a>
+  &nbsp;
+  <a href="https://github.com/pleonex/PleOps.Cake/workflows/Build%20and%20release">
+    <img alt="Build and release" src="https://github.com/pleonex/PleOps.Cake/workflows/Build%20and%20release/badge.svg?branch=main&event=push" />
+  </a>
+  &nbsp;
+  <a href="https://choosealicense.com/licenses/mit/">
+    <img alt="MIT License" src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat" />
+  </a>
+  &nbsp;
+</p>
+
+Complete DevOps workflow and best-practices for .NET projects based on
+[Cake](https://cakebuild.net/).
+
+- ♻️ DevOps best practices for a software project
+- 🔧 Build, test and release tasks for .NET projects and documentation sites
+- 📚 Documentation explaining the workflow
+- 📋 [Template repository](https://github.com/pleonex/template-csharp) ready to
+  use
+
+## Tech stack
+
+- **Projects**: C# / .NET
+- **Documentation**: DocFX, GitHub page
+- **CI**: GitHub Actions
+- **Release deployment**: NuGet feeds, GitHub
+
+## Get started
+
+Check out the [documentation site](https://www.pleonex.dev/PleOps.Cake/) to
+start learning how to use the library.
 
-Full automated build, test, stage and release pipeline for simple .NET projects
-based on Cake. Check also the
-[template repository](https://github.com/pleonex/template-csharp) to see the
-pipeline in action!
-
-Tech stack:
-
-- Projects: C# / .NET
-- Documentation: DocFX, GitHub page
-- CI: GitHub Actions
-- Release publication: NuGet feeds, GitHub
-
-<!-- prettier-ignore -->
-| Release | Package                                                           |
-| ------- | ----------------------------------------------------------------- |
-| Stable  | [![Nuget](https://img.shields.io/nuget/v/Cake.Frosting.PleOps.Recipe?label=nuget.org&logo=nuget)](https://www.nuget.org/packages/Cake.Frosting.PleOps.Recipe) |
-| Preview | [Azure Artifacts](https://dev.azure.com/benito356/NetDevOpsTest/_packaging?_a=feed&feed=PleOps) |
-
-## Requirements
+Feel free to ask any question in the
+[project discussion](https://github.com/pleonex/PleOps.Cake/discussions).
+
+## Usage
+
+The project ships a NuGet library with [Cake Frosting](https://cakebuild.net/)
+tasks:
+
+- `Cake.Frosting.PleOps.Recipe`:
+  ![Package in NuGet](https://img.shields.io/nuget/v/Cake.Frosting.PleOps.Recipe?label=nuget.org&logo=nuget)
+
+To use it, create a new console application with the
+[_Cake Frosting_ template](https://cakebuild.net/docs/getting-started/setting-up-a-new-frosting-project),
+add a reference to this recipe NuGet and its tasks will be available to use.
+
+```cs
+return new CakeHost()
+    .AddAssembly(typeof(Cake.Frosting.PleOps.Recipe.PleOpsBuildContext).Assembly)
+    .UseContext<Cake.Frosting.PleOps.Recipe.PleOpsBuildContext>()
+    .UseLifetime<BuildLifetime>()
+    .Run(args);
+
+[TaskName("Default")]
+[IsDependentOn(typeof(Cake.Frosting.PleOps.Recipe.Common.SetGitVersionTask))]
+[IsDependentOn(typeof(Cake.Frosting.PleOps.Recipe.Common.CleanArtifactsTask))]
+[IsDependentOn(typeof(Cake.Frosting.PleOps.Recipe.Dotnet.DotnetTasks.BuildProjectTask))]
+public sealed class DefaultTask : FrostingTask
+{
+}
+```
 
-- .NET 8.0 SDK
+> [!TIP]  
+> Find a detailed setup guide in the
+> [documentation site](<[docs/articles/getting-started/tutorial.md](https://www.pleonex.dev/PleOps.Cake/docs/getting-started/tutorial.html)>).
 
-## Preview versions
+### Preview releases
 
-To use a preview version, add a `nuget.config` file in the repository root
-directory with the following content:
+Preview releases are in an
+[Azure DevOps NuGet feed](https://dev.azure.com/benito356/NetDevOpsTest/_packaging?_a=feed&feed=PleOps).
+Add a `nuget.config` file in the repository root directory with the following
+content:
 
 ```xml
 <?xml version="1.0" encoding="utf-8"?>
@@ -47,25 +103,15 @@ directory with the following content:
 </configuration>
 ```
 
-## Documentation
-
-Feel free to ask any question in the
-[project Discussion site!](https://github.com/pleonex/PleOps.Cake/discussions)
-
-Check the [documentation](https://www.pleonex.dev/PleOps.Cake/) for more
-information. For reference, this is the general build and release pipeline.
-
-![release diagram](./docs/articles/workflows/images/release_automation.png)
-
 ## Build
 
 The project requires to build .NET 8.0 SDK.
 
 To build, test and generate artifacts run:
 
 ```sh
-# Build and run tests
-dotnet run --project build/orchestrator -- --target=Default
+# Build and run tests (with code coverage!)
+dotnet run --project build/orchestrator
 
 # (Optional) Create bundles (nuget, zips, docs)
 dotnet run --project build/orchestrator -- --target=Bundle