Add introduction and goals sections to the README

README.md

@@ -10,7 +10,7 @@
 
 > issuer-lib is the Go library for building cert-manager issuers.
 
-See `./internal/testsetups/simple` for an example of creating an issuer based on this library.
+## Stability disclaimer
 
 ---
 
@@ -26,6 +26,38 @@ At this point, we will start advising developers to migrate their existing Issue
 
 ---
 
+## Introduction
+
+cert-manager issuers are responsible for watching CertificateRequest resources and updating
+their status with the signed certificate data. An issuer must only respond to
+CertificateRequests that have an IssuerRef that matches the Name, Kind and group
+of one of its Issuer resources. Additionally, the CertificateRequest must have been approved.
+
+This library provides all the controllers necessary to implement a cert-manager
+issuer, these controllers contain all the common logic required to implement
+an issuer. The only thing you need to provide is the business logic for
+communicating with your CA, this is done by implementing the `Sign` and `Check`
+functions.
+
+## Goals
+
+This library makes it easy to create a cert-manager issuer that integrates with
+your CA.
+
+It takes care of:
+
+- Watching CertificateRequests and your custom Issuer resources
+- Updating the Issuer status with status of the CA
+- Updating the CertificateRequest status with the signed certificate data
+- Handling errors and retries
+- Handling CertificateRequest approval and denial
+- [FUTURE] Handle issuance of Kubernetes CSR resources
+- [FUTURE] Provide a set of conformance tests for issuers
+
+## Usage
+
+An example issuer implementation can be found in the [`./internal/testsetups/simple`](./internal/testsetups/simple) subdirectory.
+
 ## How it works
 
 This repository provides a go libary that you can use for creating cert-manager controllers for your own Issuers.