diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
index 19668ff..c5c4716 100644
--- a/RELEASE_NOTES.md
+++ b/RELEASE_NOTES.md
@@ -2,6 +2,9 @@
 
 ## XMLUnit.NET 2.11.1 - /Not Released, yet/
 
+* added readme files for the nuget packages.
+  Issue [#46](https://github.com/xmlunit/xmlunit.net/issues/46).
+
 * the NUnit 4.x constraints package tags nunit3 rather than nunit4.
   PR [#43](https://github.com/xmlunit/xmlunit.net/issues/43).
 
diff --git a/src/doc/readmes/net-constraints-nunit2/README.md b/src/doc/readmes/net-constraints-nunit2/README.md
new file mode 100644
index 0000000..6add3a2
--- /dev/null
+++ b/src/doc/readmes/net-constraints-nunit2/README.md
@@ -0,0 +1,59 @@
+# XMLUnit.NET NUnit 2.x Constraints
+
+XMLUnit provides you with the tools to verify the XML you emit is the
+one you want to create.
+
+This package provides Constraints on top of the XMLUnit.NET core
+library to be used with NUnit 2.x. If you are using a different
+version of NUUnit, please use the package for your version.
+
+* [XMLUnit.Core - Core Library ![nuget](https://img.shields.io/nuget/v/XMLUnit.Core.svg)](https://www.nuget.org/packages/XMLUnit.Core/)
+* [XMLUnit.NUnit3.Constraints - Constraints for NUnit 3.x ![nuget](https://img.shields.io/nuget/v/XMLUnit.NUnit3.Constraints.svg)](https://www.nuget.org/packages/XMLUnit.NUnit3.Constraints/)
+* [XMLUnit.NUnit4.Constraints - Constraints for NUnit 4.x ![nuget](https://img.shields.io/nuget/v/XMLUnit.NUnit4.Constraints.svg)](https://www.nuget.org/packages/XMLUnit.NUnit4.Constraints/)
+
+[![Build status](https://ci.appveyor.com/api/projects/status/am34dfbr4vbcarr3?svg=true)]
+
+## Requirements
+
+XMLUnit requires .NET Standard 2.0 (tested with .NET 8 rigt now) and
+should still support .NET Framework 3.5 and Mono.
+
+This Constraints package requires NUnit 2.x and XMLUnit.Core.
+
+## Usage
+
+These are some really small examples, more is available as part of the
+[user guide](https://github.com/xmlunit/user-guide/wiki)
+
+### Comparing Two Documents
+
+```csharp
+Assert.That(CreateTestDocument(), CompareConstraint.IsIdenticalTo(Input.FromFile("test-data/good.xml")));
+```
+
+### Asserting an XPath Value
+
+```csharp
+Assert.That("<foo>bar</foo>", HasXPathConstraint.HasXPath("/foo"));
+Assert.That("<foo>bar</foo>", EvaluateXPathConstraint.HasXPath("/foo/text()",
+```
+
+### Validating a Document Against an XML Schema
+
+
+```csharp
+Assert.That(CreateDocument(),
+            new ValidationConstraint(Input.FromFile("local.xsd")));
+```
+
+## Additional Documentation
+
+XMLUnit.NET is developed at
+[github](https://github.com/xmlunit/xmlunit.net). More documentation,
+releases and an issue tracker can be found there.
+
+## Changelog
+
+See the [Release
+Notes](https://github.com/xmlunit/xmlunit.net/blob/main/RELEASE_NOTES.md)
+at github.
diff --git a/src/doc/readmes/net-constraints-nunit3/README.md b/src/doc/readmes/net-constraints-nunit3/README.md
new file mode 100644
index 0000000..9c460ef
--- /dev/null
+++ b/src/doc/readmes/net-constraints-nunit3/README.md
@@ -0,0 +1,59 @@
+# XMLUnit.NET NUnit 3.x Constraints
+
+XMLUnit provides you with the tools to verify the XML you emit is the
+one you want to create.
+
+This package provides Constraints on top of the XMLUnit.NET core
+library to be used with NUnit 3.x. If you are using a different
+version of NUUnit, please use the package for your version.
+
+* [XMLUnit.Core - Core Library ![nuget](https://img.shields.io/nuget/v/XMLUnit.Core.svg)](https://www.nuget.org/packages/XMLUnit.Core/)
+* [XMLUnit.NUnit2.Constraints - Constraints for NUnit 2.x ![nuget](https://img.shields.io/nuget/v/XMLUnit.NUnit2.Constraints.svg)](https://www.nuget.org/packages/XMLUnit.NUnit2.Constraints/)
+* [XMLUnit.NUnit4.Constraints - Constraints for NUnit 4.x ![nuget](https://img.shields.io/nuget/v/XMLUnit.NUnit4.Constraints.svg)](https://www.nuget.org/packages/XMLUnit.NUnit4.Constraints/)
+
+[![Build status](https://ci.appveyor.com/api/projects/status/am34dfbr4vbcarr3?svg=true)]
+
+## Requirements
+
+XMLUnit requires .NET Standard 2.0 (tested with .NET 8 rigt now) and
+should still support .NET Framework 3.5 and Mono.
+
+This Constraints package requires NUnit 3.x and XMLUnit.Core.
+
+## Usage
+
+These are some really small examples, more is available as part of the
+[user guide](https://github.com/xmlunit/user-guide/wiki)
+
+### Comparing Two Documents
+
+```csharp
+Assert.That(CreateTestDocument(), CompareConstraint.IsIdenticalTo(Input.FromFile("test-data/good.xml")));
+```
+
+### Asserting an XPath Value
+
+```csharp
+Assert.That("<foo>bar</foo>", HasXPathConstraint.HasXPath("/foo"));
+Assert.That("<foo>bar</foo>", EvaluateXPathConstraint.HasXPath("/foo/text()",
+```
+
+### Validating a Document Against an XML Schema
+
+
+```csharp
+Assert.That(CreateDocument(),
+            new ValidationConstraint(Input.FromFile("local.xsd")));
+```
+
+## Additional Documentation
+
+XMLUnit.NET is developed at
+[github](https://github.com/xmlunit/xmlunit.net). More documentation,
+releases and an issue tracker can be found there.
+
+## Changelog
+
+See the [Release
+Notes](https://github.com/xmlunit/xmlunit.net/blob/main/RELEASE_NOTES.md)
+at github.
diff --git a/src/doc/readmes/net-constraints-nunit4/README.md b/src/doc/readmes/net-constraints-nunit4/README.md
new file mode 100644
index 0000000..a116f94
--- /dev/null
+++ b/src/doc/readmes/net-constraints-nunit4/README.md
@@ -0,0 +1,59 @@
+# XMLUnit.NET NUnit 4.x Constraints
+
+XMLUnit provides you with the tools to verify the XML you emit is the
+one you want to create.
+
+This package provides Constraints on top of the XMLUnit.NET core
+library to be used with NUnit 4.x. If you are using a different
+version of NUUnit, please use the package for your version.
+
+* [XMLUnit.Core - Core Library ![nuget](https://img.shields.io/nuget/v/XMLUnit.Core.svg)](https://www.nuget.org/packages/XMLUnit.Core/)
+* [XMLUnit.NUnit2.Constraints - Constraints for NUnit 2.x ![nuget](https://img.shields.io/nuget/v/XMLUnit.NUnit2.Constraints.svg)](https://www.nuget.org/packages/XMLUnit.NUnit2.Constraints/)
+* [XMLUnit.NUnit3.Constraints - Constraints for NUnit 3.x ![nuget](https://img.shields.io/nuget/v/XMLUnit.NUnit3.Constraints.svg)](https://www.nuget.org/packages/XMLUnit.NUnit3.Constraints/)
+
+[![Build status](https://ci.appveyor.com/api/projects/status/am34dfbr4vbcarr3?svg=true)]
+
+## Requirements
+
+XMLUnit requires .NET Standard 2.0 (tested with .NET 8 rigt now) and
+should still support .NET Framework 3.5 and Mono.
+
+This Constraints package requires NUnit 4.x and XMLUnit.Core.
+
+## Usage
+
+These are some really small examples, more is available as part of the
+[user guide](https://github.com/xmlunit/user-guide/wiki)
+
+### Comparing Two Documents
+
+```csharp
+Assert.That(CreateTestDocument(), CompareConstraint.IsIdenticalTo(Input.FromFile("test-data/good.xml")));
+```
+
+### Asserting an XPath Value
+
+```csharp
+Assert.That("<foo>bar</foo>", HasXPathConstraint.HasXPath("/foo"));
+Assert.That("<foo>bar</foo>", EvaluateXPathConstraint.HasXPath("/foo/text()",
+```
+
+### Validating a Document Against an XML Schema
+
+
+```csharp
+Assert.That(CreateDocument(),
+            new ValidationConstraint(Input.FromFile("local.xsd")));
+```
+
+## Additional Documentation
+
+XMLUnit.NET is developed at
+[github](https://github.com/xmlunit/xmlunit.net). More documentation,
+releases and an issue tracker can be found there.
+
+## Changelog
+
+See the [Release
+Notes](https://github.com/xmlunit/xmlunit.net/blob/main/RELEASE_NOTES.md)
+at github.
diff --git a/src/doc/readmes/net-core/README.md b/src/doc/readmes/net-core/README.md
new file mode 100644
index 0000000..e9f1b9c
--- /dev/null
+++ b/src/doc/readmes/net-core/README.md
@@ -0,0 +1,87 @@
+# XMLUnit.NET
+
+XMLUnit provides you with the tools to verify the XML you emit is the
+one you want to create.
+
+It provides helpers to validate against an XML Schema, assert the
+values of XPath queries or compare XML documents against expected
+outcomes.
+
+This package provides the core functionality and can be used
+stand-alone. In addition there are libraries providing NUnit
+constraints and a "placeholders" package that may simplify writing
+comparison tests in certain cases.
+
+* [XMLUnit.NUnit2.Constraints - Constraints for NUnit 2.x ![nuget](https://img.shields.io/nuget/v/XMLUnit.NUnit2.Constraints.svg)](https://www.nuget.org/packages/XMLUnit.NUnit2.Constraints/)
+* [XMLUnit.NUnit3.Constraints - Constraints for NUnit 3.x ![nuget](https://img.shields.io/nuget/v/XMLUnit.NUnit3.Constraints.svg)](https://www.nuget.org/packages/XMLUnit.NUnit3.Constraints/)
+* [XMLUnit.NUnit4.Constraints - Constraints for NUnit 4.x ![nuget](https://img.shields.io/nuget/v/XMLUnit.NUnit4.Constraints.svg)](https://www.nuget.org/packages/XMLUnit.NUnit4.Constraints/)
+* [XMLUnit.Placeholders - simplifies comparisons for special cases ![nuget](https://img.shields.io/nuget/v/XMLUnit.Placeholders.svg)](https://www.nuget.org/packages/XMLUnit.Placeholders/)
+
+[![Build status](https://ci.appveyor.com/api/projects/status/am34dfbr4vbcarr3?svg=true)]
+
+## Requirements
+
+XMLUnit requires .NET Standard 2.0 (tested with .NET 8 rigt now) and
+should still support .NET Framework 3.5 and Mono.
+
+The core library hasn't got any dependencies itself.
+
+## Usage
+
+These are some really small examples, more is available as part of the
+[user guide](https://github.com/xmlunit/user-guide/wiki)
+
+### Comparing Two Documents
+
+```csharp
+ISource control = Input.FromFile("test-data/good.xml").Build();
+ISource test = Input.FromByteArray(CreateTestDocument()).Build();
+IDifferenceEngine diff = new DOMDifferenceEngine();
+diff.DifferenceListener += (comparison, outcome) => {
+            Assert.Fail("found a difference: {}", comparison);
+        };
+diff.Compare(control, test);
+```
+
+or using the fluent builder API
+
+```csharp
+Diff d = DiffBuilder.Compare(Input.FromFile("test-data/good.xml"))
+             .WithTest(CreateTestDocument()).Build();
+Assert.IsFalse(d.HasDifferences());
+```
+
+### Asserting an XPath Value
+
+```csharp
+ISource source = Input.FromString("<foo>bar</foo>").Build();
+IXPathEngine xpath = new XPathEngine();
+IEnumerable<XmlNode> allMatches = xpath.SelectNodes("/foo", source);
+string content = xpath.evaluate("/foo/text()", source);
+```
+
+### Validating a Document Against an XML Schema
+
+
+```csharp
+Validator v = Validator.ForLanguage(Languages.W3C_XML_SCHEMA_NS_URI);
+v.SchemaSources = new ISource[] {
+        Input.FromUri("http://example.com/some.xsd").Build(),
+        Input.FromFile("local.xsd").Build()
+    };
+ValidationResult result = v.ValidateInstance(Input.FromDocument(CreateDocument()).Build());
+bool valid = result.Valid;
+IEnumerable<ValidationProblem> problems = result.Problems;
+```
+
+## Additional Documentation
+
+XMLUnit.NET is developed at
+[github](https://github.com/xmlunit/xmlunit.net). More documentation,
+releases and an issue tracker can be found there.
+
+## Changelog
+
+See the [Release
+Notes](https://github.com/xmlunit/xmlunit.net/blob/main/RELEASE_NOTES.md)
+at github.
diff --git a/src/doc/readmes/net-placeholders/README.md b/src/doc/readmes/net-placeholders/README.md
new file mode 100644
index 0000000..9667f07
--- /dev/null
+++ b/src/doc/readmes/net-placeholders/README.md
@@ -0,0 +1,70 @@
+# XMLUnit.NET
+
+XMLUnit provides you with the tools to verify the XML you emit is the
+one you want to create.
+
+This package provides a way to simplify comparisons by using a control
+document with a simple expression language to compare against.
+
+## Requirements
+
+XMLUnit requires .NET Standard 2.0 (tested with .NET 8 rigt now) and
+should still support .NET Framework 3.5 and Mono.
+
+The placeholders package only depends on XMLUnit.Core.
+
+## Usage
+
+More documentaion is available as part of
+the [user guide](https://github.com/xmlunit/user-guide/wiki).
+
+If you are creating documents with a structure like
+
+```xml
+<message>
+  <id>12345</id>
+  <content>Hello</content>
+</message>
+```
+
+and can't predict the `id` inside your tests but still want to assert
+it is a number, using just the core library will require some custom
+code as a `IDifferenceEvaluator`
+
+Using the placeholders package you can write a control document like
+
+```xml
+<message>
+  <id>${xmlunit.isNumber}</id>
+  <content>Hello</content>
+</message>
+```
+
+and run the test like
+
+```csharp
+string control = <the above>;
+string test = <the program output>;
+Diff diff = DiffBuilder.Compare(control).WithTest(test)
+    .WithDifferenceEvaluator(new PlaceholderDifferenceEvaluator()).build();
+Assert.IsFalse(d.HasDifferences());
+```
+
+Currently the fillowing placeholders are defined:
+
+* `${xmlunit.ignore}` to completely ignore the element
+* `${xmlunit.isNumber}`
+* `${xmlunit.matchesRegex()}` with regex parameter
+* `${xmlunit.isDateTime()}` with optional format parameter
+
+## Additional Documentation
+
+XMLUnit.NET is developed at
+[github](https://github.com/xmlunit/xmlunit.net). More documentation,
+releases and an issue tracker can be found there.
+
+## Changelog
+
+See the [Release
+Notes](https://github.com/xmlunit/xmlunit.net/blob/main/RELEASE_NOTES.md)
+at github.
diff --git a/src/main/net-constraints-nunit2/XMLUnit.NUnit2.Constraints.nuspec b/src/main/net-constraints-nunit2/XMLUnit.NUnit2.Constraints.nuspec
index e4139bc..b39a6aa 100644
--- a/src/main/net-constraints-nunit2/XMLUnit.NUnit2.Constraints.nuspec
+++ b/src/main/net-constraints-nunit2/XMLUnit.NUnit2.Constraints.nuspec
@@ -22,10 +22,12 @@
       <frameworkAssembly assemblyName="System.Xml.Linq" />
     </frameworkAssemblies>
     <tags>xmlunit xml unit-testing test xmldiff nunit nunit2</tags>
+    <readme>docs\README.md</readme>
   </metadata>
   <files>
     <file src="..\..\..\build/NetFramework/bin/Release/xmlunit-nunit2-constraints.dll" target="lib\net35"/>
     <file src="..\..\..\build/NetFramework/bin/Release/xmlunit-nunit2-constraints.pdb" target="lib\net35"/>
     <file src="..\..\..\build/NetFramework/bin/Release/xmlunit-nunit2-constraints.xml" target="lib\net35"/>
+    <file src="..\..\doc/readmes/net-constraints-nunit2/README.md" target="docs"/>
   </files>
 </package>
diff --git a/src/main/net-constraints-nunit3/XMLUnit.NUnit3.Constraints.nuspec b/src/main/net-constraints-nunit3/XMLUnit.NUnit3.Constraints.nuspec
index eaed99c..4700ee1 100644
--- a/src/main/net-constraints-nunit3/XMLUnit.NUnit3.Constraints.nuspec
+++ b/src/main/net-constraints-nunit3/XMLUnit.NUnit3.Constraints.nuspec
@@ -22,6 +22,7 @@
       <frameworkAssembly assemblyName="System.Xml.Linq" />
     </frameworkAssemblies>
     <tags>xmlunit xml unit-testing test xmldiff nunit nunit3</tags>
+    <readme>docs\README.md</readme>
   </metadata>
   <files>
     <file src="..\..\..\build/NetFramework/bin/Release/xmlunit-nunit3-constraints.dll" target="lib\net35"/>
@@ -30,5 +31,6 @@
     <file src="..\..\..\build/bin/Release/netstandard2.0/xmlunit-nunit3-constraints.dll" target="lib\netstandard2.0"/>
     <file src="..\..\..\build/bin/Release/netstandard2.0/xmlunit-nunit3-constraints.pdb" target="lib\netstandard2.0"/>
     <file src="..\..\..\build/bin/Release/netstandard2.0/xmlunit-nunit3-constraints.xml" target="lib\netstandard2.0"/>
+    <file src="..\..\doc/readmes/net-constraints-nunit3/README.md" target="docs"/>
   </files>
 </package>
diff --git a/src/main/net-constraints-nunit4/XMLUnit.NUnit4.Constraints.nuspec b/src/main/net-constraints-nunit4/XMLUnit.NUnit4.Constraints.nuspec
index b08006f..10d189a 100644
--- a/src/main/net-constraints-nunit4/XMLUnit.NUnit4.Constraints.nuspec
+++ b/src/main/net-constraints-nunit4/XMLUnit.NUnit4.Constraints.nuspec
@@ -22,6 +22,7 @@
       <frameworkAssembly assemblyName="System.Xml.Linq" />
     </frameworkAssemblies>
     <tags>xmlunit xml unit-testing test xmldiff nunit nunit4</tags>
+    <readme>docs\README.md</readme>
   </metadata>
   <files>
     <file src="..\..\..\build/NetFramework/bin/Release/xmlunit-nunit4-constraints.dll" target="lib\net462"/>
@@ -30,5 +31,6 @@
     <file src="..\..\..\build/bin/Release/net6.0/xmlunit-nunit4-constraints.dll" target="lib\net6.0"/>
     <file src="..\..\..\build/bin/Release/net6.0/xmlunit-nunit4-constraints.pdb" target="lib\net6.0"/>
     <file src="..\..\..\build/bin/Release/net6.0/xmlunit-nunit4-constraints.xml" target="lib\net6.0"/>
+    <file src="..\..\doc/readmes/net-constraints-nunit4/README.md" target="docs"/>
   </files>
 </package>
diff --git a/src/main/net-core/XMLUnit.Core.nuspec b/src/main/net-core/XMLUnit.Core.nuspec
index c6b847f..6e6ea92 100644
--- a/src/main/net-core/XMLUnit.Core.nuspec
+++ b/src/main/net-core/XMLUnit.Core.nuspec
@@ -17,6 +17,7 @@
       <frameworkAssembly assemblyName="System.Xml.Linq" />
     </frameworkAssemblies>
     <tags>xmlunit xml unit-testing test xmldiff</tags>
+    <readme>docs\README.md</readme>
   </metadata>
   <files>
     <file src="..\..\..\build/NetFramework/bin/Release/xmlunit-core.dll" target="lib\net35"/>
@@ -25,5 +26,6 @@
     <file src="..\..\..\build/bin/Release/netstandard2.0/xmlunit-core.dll" target="lib\netstandard2.0"/>
     <file src="..\..\..\build/bin/Release/netstandard2.0/xmlunit-core.pdb" target="lib\netstandard2.0"/>
     <file src="..\..\..\build/bin/Release/netstandard2.0/xmlunit-core.xml" target="lib\netstandard2.0"/>
+    <file src="..\..\doc/readmes/net-core/README.md" target="docs"/>
   </files>
 </package>
diff --git a/src/main/net-placeholders/XMLUnit.Placeholders.nuspec b/src/main/net-placeholders/XMLUnit.Placeholders.nuspec
index 1f52af8..bc9643d 100644
--- a/src/main/net-placeholders/XMLUnit.Placeholders.nuspec
+++ b/src/main/net-placeholders/XMLUnit.Placeholders.nuspec
@@ -20,6 +20,7 @@
       <frameworkAssembly assemblyName="System.Xml" />
     </frameworkAssemblies>
     <tags>xmlunit xml unit-testing test xmldiff</tags>
+    <readme>docs\README.md</readme>
   </metadata>
   <files>
     <file src="..\..\..\build/NetFramework/bin/Release/xmlunit-placeholders.dll" target="lib\net35"/>
@@ -28,5 +29,6 @@
     <file src="..\..\..\build/bin/Release/netstandard2.0/xmlunit-placeholders.dll" target="lib\netstandard2.0"/>
     <file src="..\..\..\build/bin/Release/netstandard2.0/xmlunit-placeholders.pdb" target="lib\netstandard2.0"/>
     <file src="..\..\..\build/bin/Release/netstandard2.0/xmlunit-placeholders.xml" target="lib\netstandard2.0"/>
+    <file src="..\..\doc/readmes/net-placeholders/README.md" target="docs"/>
   </files>
 </package>