JSON tutorial

docs/site/Writerside/topics/Specifying-pre-set-values.md

@@ -5,7 +5,7 @@ In this tutorial, we'll look at how we can have pre-set values on our types.
 Pre-set values have two common uses:
 
 1. to represent known values
-2. to represent values that cannot be created by _users_ of a Value Object
+2. to represent values that _users_ of a Value Object can’t create
 
 Let's look at the first scenario, representing known values. Create the following type:
 
@@ -44,7 +44,7 @@ Now, let's take a look at the other scenario of representing values that can't (
 created externally. The term 'externally' user here, means **users** of the class.
 
 Let's revisit our `CustomerId` from the [validation tutorial](ValidationTutorial.md). We want to say that an instance
-with a value of zero means that the customer was not specified, but we don't want users to explicitly create
+with a value of zero means that the customer wasn’t specified, but we don't want users to explicitly create
 instances with a value of zero. Let's try it out. Create this type again:  
 
 ```C#

docs/site/Writerside/topics/Using-with-JSON.md

@@ -1,16 +1,57 @@
-# Working with JSON
+# Serializing to and from JSON
 
-<note>
-This topic is incomplete and is currently being improved.
-</note>
+In this tutorial, we'll see how to serialize and deserialize value objects.
 
-As well as System.Text.Json (STJ), Vogen also generates the code to work with Newtonsoft.Json (NSJ)
+Vogen can automatically generate the code required for this.
+It supports both System.Text.Json (STJ), and Newtonsoft.Json (NSJ)
 
-They are controlled by the `Conversions` enum. The following has serializers for NSJ and STJ:
+First, let's see what we get with no conversion generated. 
+In a C# project that references Vogen, create the following type:
 
 ```c#
-[ValueObject<float>(conversions: Conversions.NewtonsoftJson | Conversions.SystemTextJson)]
+[ValueObject<float>(conversions: Conversions.None)]
 public readonly partial struct Celsius { }
 ```
 
-See the examples folder for more information.
+Now, serialize an instance of `Celsius` to a JSON string using Newtonsoft.Json:
+
+```C#
+var weather = new
+{
+    Summary = "Sunny and hot",
+    TemperatureTodayInCelsius = Celsius.From(30)
+};
+
+Console.WriteLine(JsonSerializer.Serialize(weather));
+```
+
+You'll see:
+
+```Bash
+{"Summary":"Sunny and hot","TemperatureTodayInCelsius":{"Value":30}}
+```
+
+Note that the serializer has written the temperature as a composite object (`Value:30`).
+
+This isn't ideal as you probably want the primitive value written.
+And also, Vogen won't be able to serialize that composite value back into a value object.
+
+To get just the primitive value written, change `Celcius` to this and rerun.
+
+```c#
+[ValueObject<float>(Conversions.SystemTextJson)]
+public readonly partial struct Celsius { }
+```
+
+This outputs:
+
+```Bash
+{ Summary = Sunny and hot, TemperatureTodayInCelsius = 30 }
+```
+
+As well as treating the value object as a primitive, it also allows it to be deserialized back into a value object.
+Not that System.Text.Json is generated by default, so you could remove the `Conversions` parameter altogether.
+
+In this tutorial, we've seen how JSON is serialized if no conversions are specified, and then we've seen the difference
+that specifying the conversion makes.
+