Added more documentation

Author: linkdotnet

README.md

@@ -33,7 +33,7 @@ The library works best for a small to medium amount of strings (not multiple 100
 The normal use case is to add concatenate strings in a hot-path where the goal is to put as minimal pressure on the GC as possible.
 
 ## Documentation
-A more detailed documentation can be found [here](https://linkdotnet.github.io/StringBuilder/).
+A more detailed documentation can be found [here](https://linkdotnet.github.io/StringBuilder/). It is really important to understand how the `ValueStringBuilder` works so that you not run into weird situations where performance / allocations can even rise.
 
 ## Benchmark
 

docs/site/articles/pass_to_method.md

@@ -0,0 +1,42 @@
+---
+uid: pass_to_method
+---
+
+# Passing the `ValueStringBuilder` to a method
+
+As the [ValueStringBuilder](xref:LinkDotNet.StringBuilder.ValueStringBuilder) is `ref struct` you should be careful when passing the instance around. You should pass the reference and not the instance.
+
+
+```csharp
+public void MyFunction()
+{
+    var stringBuilder = new ValueStringBuilder();
+    stringBuilder.Append("Hello ");
+    AppendMore(ref stringBuilder);
+}
+
+private void AppendMore(ref ValueStringBuilder builder)
+{
+    builder.Append("World");
+}
+```
+
+This will print: `Hello World`
+
+> :warning: The following code snippet will show how it *does not* work. If the instance is passed not via reference but via value then first allocations will happen and second the end result is not what one would expect.
+
+```csharp
+public void MyFunction()
+{
+    var stringBuilder = new ValueStringBuilder();
+    stringBuilder.Append("Hello ");
+    AppendMore(stringBuilder);
+}
+
+private void AppendMore(ValueStringBuilder builder)
+{
+    builder.Append("World");
+}
+```
+
+This will print: `Hello `.

docs/site/articles/toc.yml

@@ -3,6 +3,8 @@
   items:
     - name: How does it work?
       href: concepts.md
+    - name: Passing the ValueStringBuilder to a method
+      href: pass_to_method.md
     - name: Comparison
       href: comparison.md
 - name: Known limitations