docs: add information and examples to adr readme

Author: thunderbiscuit

docs/adr/01-naming.md

@@ -1,17 +1,21 @@
 # Naming convention
+
 Producing language bindings potentially requires renaming a number of types and methods, and this document outlines the approach we have decided to take when thinking through this problem for bdk-ffi libraries.
 
 ## Context and Problem Statement
+
 The tool we use to produce language bindings for bdk-ffi libraries is [uniffi]. While the library is powerful, it also comes with some caveats. Some of those include the inability to expose to foreign bindings Rust-specific types like tuples, and the inability to expose generics. This means that at least _some_ wrapping and transforming of certain things are required between the pure Rust code coming from the bdk library and the final language bindings in Swift, Kotlin, and Python.
 
 With wrapping comes (a) the requirement for naming potentially new types, and (b) the ability to "wrap" behaviour that could be useful for end users. This document addresses point (a).
 
 ## Decision Drivers
+
 Our main goals are:
 1. Keep the multiple language bindings libraries maintainable.
-2. Help user of bdk help each other and working with a similarly shaped API across languages.
+2. Help users of bdk help each other and working with a similarly shaped API across languages.
 
 ## Decision Outcome
+
 We decided to try and keep the names of all types the same between the Rust libraries and the bindings, and in cases where new types had to be created, to keep them in the style and spirit of the bdk and rust-bitcoin libraries.
 
 There is so far one exception to this rule, where we renamed the `ScriptBuf` type from rust-bitcoin to `Script`. This was done because the concept of owned vs. borrowed types is strictly a Rust concept, and is not passed onto the languages bindings in any way, and therefore keeping the script type as `Script` was our preferred option in this case.

docs/adr/02-wrapping.md

@@ -1,17 +1,21 @@
 # Wrapping BDK APIs
+
 Producing language bindings potentially requires wrapping a number of APIs, and this document outlines the approach we have decided to take when thinking through this problem for bdk-ffi libraries.
 
 ## Context and Problem Statement
+
 The tool we use to produce language bindings for bdk-ffi libraries is [uniffi]. While the library is powerful, it also comes with some caveats. Some of those include the inability to expose to foreign bindings Rust-specific types like tuples, and the inability to expose generics. This means that at least _some_ wrapping and transforming of certain things are required between the pure Rust code coming from the bdk library and the final language bindings in Swift, Kotlin, and Python.
 
 With wrapping comes (a) the requirement for naming potentially new types, and (b) the ability to "wrap" behaviour that could be useful for end users. This document addresses point (b).
 
 ## Decision Drivers
+
 Our main goals are:
 1. Keep the multiple language bindings libraries maintainable.
-2. Help user of bdk help each other and working with a similarly shaped API across languages.
+2. Help users of bdk help each other and working with a similarly shaped API across languages.
 
 ## Decision Outcome
+
 There are three potential reasons for wrapping Rust BDK APIs:
 1. The Rust types are not available in the target language (e.g., a function returns a tuple, which can't be returned in Swift/Kotlin)
 2. Some complex functionality is available in the Rust bitcoin/miniscript/bdk ecosystem, but exposing all underlying types required for this functionality is out of scope at the time a particular feature is required

docs/adr/README.md

@@ -1,2 +1,12 @@
 # Architectural Decision Records
-This directory contains a series of Architectural Decision Records or "ADRs" for the uniffi project. We're going to try to use it as a kind of collective memory of the decisions we've made and the path we've taken to get the project to its current point.
+
+This directory contains a series of Architectural Decision Records or "ADRs" for the bdk-ffi project. We're going to use it as a kind of collective memory of the decisions we've made and the path we've taken to get the project to its current point.
+
+A good example of simple and well executed ADRs can be found on the [uniffi](https://github.com/mozilla/uniffi-rs/) project repository. See their [readme](https://github.com/mozilla/uniffi-rs/tree/main/docs/adr) and [template](https://github.com/mozilla/uniffi-rs/blob/main/docs/adr/template.md) for more information.
+
+Some more readings on ADRs:
+- https://www.ozimmer.ch/practices/2023/04/03/ADRCreation.html
+- https://github.com/joelparkerhenderson/architecture-decision-record
+- https://adr.github.io/
+- https://betterprogramming.pub/the-ultimate-guide-to-architectural-decision-records-6d74fd3850ee
+- https://www.redhat.com/architect/architecture-decision-records