Enhance documentation

README.md

@@ -1,12 +1,13 @@
 # FSharp.MongoDB
 
-> an F# interface for the MongoDB .NET driver
+> an F# interface for the MongoDB .NET [C# driver][csharp_driver].
 
 ## Goals of this project
 
   * Provide an idiomatic F# API for interacting with MongoDB.
   * Have an implementation that is fully testable without connecting to a server.
-
+  * Isomorphic bson serialization for C# and F#.
+
 ## FSharp.MongoDB history
 
 Repository origins are:
@@ -43,6 +44,46 @@ On startup you have to register serializers:
 MongoDB.Bson.Serialization.FSharp.register()
 ```
 
+# Serialization format
+
+## List
+`List<_>` is serialized as an array. Order is preserved.
+
+## Set
+`Set<_>` is serialized as an array. Do not rely on the order.
+
+## Array
+`List<_>` is serialized as an array. Order is preserved.
+
+## Seq
+`Seq<_>` is serialized as an array. Order is preserved.
+
+## Map
+`Map<_, _>` is serialized as an object. Do not rely on the order of the keys.
+
+## Option
+`Option<_>` is either serialized as:
+* `null` if `Option.None`
+* `object` if `Option.Some`
+
+On deserialization, missing value is mapped to `None`.
+
+## ValueOption
+`ValueOption<_>` is either serialized as:
+* `null` if `ValueOption.ValueNone`
+* `object` if `ValueOption.ValueSome`
+
+On deserialization, missing value is mapped to `ValueNone`.
+
+## Record
+A record is serialized as an `object.
+
+If you want to auto-generate `ObjectId` (as the Id of the collection), add `[<CLIMutable>]` on the record.
+
+## Discriminated union
+The case of the discriminated union is stored in `_t` key.
+Each value of the DU is serialized as an `object` using its corresponding value name.
+
 # License
 The contents of this library are made available under the [Apache License, Version 2.0][license].