docs: improve README

tlux · tlux · commit 225dfa46dda8 · 2024-03-24T21:39:34.000+01:00
diff --git a/README.md b/README.md
@@ -24,31 +24,37 @@ end
 
 ## Usage
 
-With Vx, you can define schemata to validate complex data against.
+With Vx, you have the capability to define schemata for validating complex data
+effortlessly.
 
 You first need to define your schema.
 
 ```elixir
 schema = Vx.String.t()
 ```
 
-Then, you can call `Vx.validate/2` or `Vx.validate!/2` to check if a given
+After that, you can call `Vx.validate/2` or `Vx.validate!/2` to check if a given
 values matches:
 
 ```elixir
 Vx.validate(schema, "foo")
 # :ok
 ```
 
-When the value does not match, an error is returned (or raised respectively)
-pointing out what is wrong:
+When the value does not match, an error is returned (or raised, respectively),
+indicating the specific issue.
+
+```elixir
+Vx.validate(schema, 123)
+# {:error, %Vx.Error{...}}
+```
 
 ```elixir
 Vx.validate!(schema, 123)
 # ** (Vx.Error) must be a string
 ```
 
-Some types can be augmented with additional constraints by piping everything
+Additional constraints can be added to certain types by piping everything
 together:
 
 ```elixir
