Update VECTOR documentation based on review feedback

Author: alina-derkach-oaza

docs/distance-function.md

@@ -1,8 +1,8 @@
 # DISTANCE() Function
 
-The `DISTANCE()` function calculates the distance between two `VECTOR` values. Use this function to compare vectors for similarity search and other vector-based operations.
+The `DISTANCE()` function computes the distance between two `VECTOR` values to enable similarity searches and other vector-based operations.
 
-A vector is an ordered list of numeric values, such as `[1, 2, 3]`. The distance between two vectors is a numeric value that indicates how different the vectors are.
+A vector is an ordered list of numeric values, such as `[1, 2, 3]`. The distance between two vectors is a numeric value that indicates how similar the vectors are.
 
 A distance metric defines how the function calculates this value. Different metrics compare properties such as vector values, direction, or magnitude. In general, a smaller distance indicates greater similarity.
 
@@ -21,7 +21,8 @@ Both functions require exactly three arguments.
 
 `DISTANCE()` accepts the following arguments:
 
-* `vector_a` and `vector_b` specify the vectors to compare. Both arguments must be `VECTOR` values or binary strings that represent float vectors. Other data types cause an error. The vectors must have the same number of dimensions. A dimension mismatch causes an error.
+* `vector_a` and `vector_b` specify the vectors to compare. Both arguments must be values of `VECTOR` data type or binary strings that represent float vectors. Other data types cause an error. The vectors must have the same dimension. A dimension mismatch causes an error.
+
 * `metric` specifies the distance metric. Use a constant string or hex literal that resolves to a supported metric. Metric names are case-insensitive. You cannot use a column reference or a computed expression, such as `CONCAT()`, for this argument.
 
 For a binary-string vector, the byte length must be a multiple of 4 because each vector element is a 4-byte single-precision floating-point value. An invalid byte length causes an error.
@@ -70,15 +71,13 @@ The result is a `DOUBLE` value:
 
 ??? example "Expected output"
 
-````
-```text
-+-------------------+
-| distance          |
-+-------------------+
-| 5.196152422706632 |
-+-------------------+
-```
-````
+    ```text
+    +-------------------+
+    | distance          |
+    +-------------------+
+    | 5.196152422706632 |
+    +-------------------+
+    ```
 
 ### Use another distance metric
 

docs/vector.md

@@ -1,6 +1,6 @@
 # The VECTOR Type
 
-The `VECTOR` data type stores an ordered list of numeric values, called a vector, in a table column. For example, `[0.1, 0.2, 0.3]` represents a vector with three values.
+The `VECTOR` data type stores an ordered list of numeric values, called a vector, in a table column. For example, `[0.1, 0.3, 0.2]` represents a vector with three elements.
 
 Vectors can represent numerical features, such as embeddings used for similarity search and machine learning. Each element in a `VECTOR` value uses a single-precision floating-point number.
 
@@ -10,9 +10,9 @@ Vectors can represent numerical features, such as embeddings used for similarity
 VECTOR(N)
 ```
 
-`N` specifies the number of elements, or dimensions, in the vector. All values stored in the column must have the same number of dimensions.
+`N` specifies the dimension of the `VECTOR` column and defines the maximum number of elements that a stored vector can contain.
 
-For example, the following statement creates an `embedding` column that stores three-dimensional vectors:
+For example, the following statement creates an `embedding` column with a dimension of three:
 
 ```sql
 CREATE TABLE documents (
@@ -22,24 +22,26 @@ CREATE TABLE documents (
 );
 ```
 
-A `VECTOR(3)` value contains exactly three elements, such as `[0.1, 0.2, 0.3]`. A vector with two or four elements does not match the column dimension.
+A `VECTOR(3)` column can store a vector with up to three elements. For example, it accepts vectors with two or three elements but rejects a vector with four elements.
+
+Using the same number of elements as the declared dimension is strongly recommended.
 
 ## Store vector values
 
 Use `TO_VECTOR()` to convert the string representation of a vector to a `VECTOR` value.
 
-The following statement inserts a three-dimensional vector into the `embedding` column:
+The following statement inserts a three-element vector into the `embedding` column:
 
 ```sql
 INSERT INTO documents (id, title, embedding)
 VALUES (
     1,
     'Example document',
-    TO_VECTOR('[0.1, 0.2, 0.3]')
+    TO_VECTOR('[0.1, 0.3, 0.2]')
 );
 ```
 
-The number of elements passed to `TO_VECTOR()` must match the dimension of the `VECTOR` column.
+The number of elements in the vector must not exceed the dimension specified for the `VECTOR` column.
 
 ## Retrieve vector values
 
@@ -54,19 +56,21 @@ FROM documents;
 
 Vector applications often compare vectors to determine how similar they are. The result of a comparison is a numeric distance between the vectors.
 
-Use `DISTANCE()` to calculate this distance with a supported distance metric. For example:
+Use `DISTANCE()` to calculate the distance between two vectors with a supported distance metric. The two vector values passed to `DISTANCE()` must contain the same number of elements. A mismatch causes an error.
+
+For example:
 
 ```sql
 SELECT DISTANCE(
     embedding,
-    TO_VECTOR('[0.1, 0.2, 0.3]'),
+    TO_VECTOR('[0.1, 0.3, 0.2]'),
     'COSINE'
 ) AS distance
 FROM documents;
 ```
 
-Different distance metrics compare vectors in different ways. For details about the supported metrics, arguments, and return values, see [DISTANCE() Function](distance-function.md).
+Different distance metrics compare vectors in different ways. For details about supported metrics, arguments, and return values, see [DISTANCE() Function](distance-function.md).
 
 ## See also
 
-- [DISTANCE() Function](distance-function.md)
+* [DISTANCE() Function](distance-function.md)