-A shared data layer connection is instantiated to a namespace and data is
-always read and modified within the namespace. Namespace provides data isolation across clients.
-Namespace instantiation happens when the sdlgo instance is created.
-E.g. the following code sets the SDL instance to use "example" as a namespace
- sdl := sdlgo.NewSdlInstance("example", sdlgo.NewDatabase())
-Applications can use several namespaces at the same time by creating several sdlgo instances.
+Namespace concept in a shared data layer connection is to isolate data write and read operations
+to happen within particular namespace.
+
+SDL instance
+
+There are two ways to create SDL instance, the first preferable option is to create so called
+SDL multi-namespace instance with `sdlgo.NewSyncStorage` call. The second option is to create
+SDL instance with `sdlgo.NewSdlInstance` call. Latter SDL instance creation method is deprecated
+and it should not be used anymore in any new application implementations, it is left to SDL API
+to guarantee backward compatibility for the old application implementations.
+The difference between multi-namespace `SyncStorage` SDL instance and the old one is that in
+`SyncStorage` case namespace is not defined at instance creation time, but it is defined when
+SDL read and write APIs are called. This means that with SDL `SyncStorage` instance it is much
+easier to write and read data from different namespaces in a single application client compared
+to the old SDL API where you needed to create own SDL instance for each namespace going to be
+used later to write and read data.