refactor sidebars.

docs/getting-started.md → docs/basic-building-blocks.md

@@ -1,17 +1,11 @@
 ---
-id: getting-started 
-title: "Getting Started"
+id: basic-building-blocks
+title: "Basic Building Blocks"
 ---
 
 To get started, first we need to understand that a ZIO Schema is basically built-up from these three
 sealed traits: `Record[R]`, `Enum[A]` and `Sequence[Col, Elem]`, along with the case class `Primitive[A]`. Every other type is just a specialisation of one of these (or not relevant to get you started).
 
-We will take a look at them now.
-
-## Basic Building Blocks
-
-### Schema
-
 The core data type of ZIO Schema is a `Schema[A]` which is **invariant in `A`** by necessity, because a Schema allows us to derive operations that produce an `A` but also operations that consume an `A` and that imposes limitations on the types of **transformation operators** and **composition operators** that we can provide based on a `Schema`.
 
 It looks kind of like this (simplified):
@@ -24,7 +18,7 @@ sealed trait Schema[A] { self =>
 }
 ```
 
-### Primitives
+## Primitives
 
 To describe scalar data type `A`, we use the `Primitive[A]` data type which basically is a wrapper around `StandardType`:
 
@@ -61,7 +55,7 @@ val intSchema1: Schema[Int] = Schema[Int]
 val intSchema2: Schema[Int] = Schema.primitive[Int] 
 ```
 
-### Fail
+## Fail
 
 To represents the absence of schema information for the given `A` type, we can use `Schema.fail` constructor, which creates the following schema:
 
@@ -74,9 +68,9 @@ object Schema {
 }
 ```
 
-### Collections
+## Collections
 
-#### Sequence
+### Sequence
 
 Often we have a type that is a collection of elements. For example, we might have a `List[User]`. This is called a `Sequence` and is represented using the `Sequence[Col, Elem, I]` type class:
 
@@ -137,7 +131,7 @@ object Person {
 }
 ```
 
-#### Map
+### Map
 
 Likewise, we can have a type that is a map of keys to values. ZIO Schema represents this using the following type class:
 
@@ -170,7 +164,7 @@ object Person {
 }
 ```
 
-#### Set
+### Set
 
 The `Set` type class is similar to `Sequence` and `Map`. It is used to represent a schema for a set of elements:
 
@@ -202,7 +196,7 @@ object Person {
 }
 ```
 
-### Records
+## Records
 
 Our data structures usually are composed of a lot of types. For example, we might have a `User` type that has a `name` field, an `age` field, an `address` field, and a `friends` field.
 
@@ -299,7 +293,7 @@ object Schema {
 }
 ```
 
-### Enumerations
+## Enumerations
 
 Other times, you might have a type that represents a list of different types. For example, we might have a type, like this:
 
@@ -364,7 +358,7 @@ object Schema {
 }
 ```
 
-### Optionals
+## Optionals
 
 To create a `Schema` for optional values, we can use the `Optional` type class:
 
@@ -383,7 +377,7 @@ Using the `Schema.option[A]` constructor, makes it easier to do so:
 val option: Schema[Option[Person]] = Schema.option[Person]
 ```
 
-### Either
+## Either
 
 Here is the same but for `Either`:
 
@@ -404,7 +398,7 @@ val eitherPersonSchema: Schema[scala.util.Either[String, Person]] =
   Schema.either[String, Person]
 ```
 
-### Tuple
+## Tuple
 
 Each schema has a `Schema#zip` operator that allows us to combine two schemas and create a schema for a tuple of the two types:
 

docs/index.md

@@ -10,6 +10,31 @@ sidebar_label: "Introduction"
 
 ## Introduction
 
+ZIO Schema helps us to solve some of the most common problems in distributed computing, such as serialization, deserialization, and data migration.
+
+```scala
+trait Schema[A] {
+  def schema: Schema[A]
+}
+```
+
+The trait `Schema[A]` is the core data type of this library. The `Schema[A]` is a description of the structure of a data type `A`, it is a data type that describes other data types. It is a first-class value that can be passed around, composed, and manipulated.
+
+It turns a compiled-time construct (the type of a data structure) into a runtime construct (a value that can be read, manipulated, and composed at runtime).
+
+## What Problems Does ZIO Schema Solve?
+
+1. Metaprogramming without macros, reflection or complicated implicit derivations.
+   1. Creating serialization and deserialization codecs for any supported protocol (JSON, protobuf, etc.)
+   2. Deriving standard type classes (`Eq`, `Show`, `Ordering`, etc.) from the structure of the data
+   4. Default values for data types
+2. Automate ETL (Extract, Transform, Load) pipelines
+   1. Diffing: diffing between two values of the same type
+   2. Patching: applying a diff to a value to update it
+   3. Migration: migrating values from one type to another
+3. Computations as data: Not only we can turn types into values, but we can also turn computations into values. This opens up a whole new world of possibilities in respect to distributed computing.
+   1. Optics
+
 Schema is a structure of a data type. ZIO Schema reifies the concept of structure for data types. It makes a high-level description of any data type and makes them as first-class values.
 
 Creating a schema for a data type helps us to write codecs for that data type. So this library can be a host of functionalities useful for writing codecs and protocols like JSON, Protobuf, CSV, and so forth.

docs/motivation.md

@@ -1,6 +1,7 @@
 ---
 id: motivation
-title: "Understanding The Motivation Behind ZIO Schema"
+title: "The Motivation Behind ZIO Schema"
+sidebar_label: "Motivation"
 ---
 
 ZIO Schema is a library used in many ZIO projects such as _ZIO Flow_, _ZIO Redis_, _ZIO Web_, _ZIO SQL_ and _ZIO DynamoDB_. It is all about reification of our types. Reification means transforming something abstract (e.g. side effects, accessing fields, structure)  into something "real" (values).

docs/sidebars.js

@@ -6,19 +6,18 @@ const sidebars = {
       collapsed: false,
       link: { type: "doc", id: "index" },
       items: [
+        "motivation",
         "use-cases",
+        "basic-building-blocks",
         {
           type: "category",
           label: "Writing Schema",
           collapsed: true,
-          link: { type: "doc", id: "index" },
           items: [
             "manual-schema-construction",
             "automatic-schema-derivation"
           ],
         },
-        "motivation",
-        "getting-started",
         "transforming-schemas",
         "codecs",
         "protobuf-example",