Docs improvements (#1269)

* Improve docs

* Formatting

* Fix links

* Update website/docs/reference/sql/aggregate_functions.md

Co-authored-by: Phillip LeBlanc <phillip@spice.ai>

* Update website/docs/reference/sql/dml.md

Co-authored-by: Phillip LeBlanc <phillip@spice.ai>

* Update website/docs/reference/sql/explain.md

Co-authored-by: Phillip LeBlanc <phillip@spice.ai>

---------

Co-authored-by: Phillip LeBlanc <phillip@spice.ai>

Author: lukekim

README.md

@@ -1,21 +1,23 @@
-# Spice.ai OSS documentation
+# Spice.ai OSS Documentation
 
-If you are looking to explore the Spice.ai OSS documentation, please go to the documentation website:
+This repository contains the source files for the Spice.ai OSS documentation website.
 
-[**https://docs.spiceai.org**](https://docs.spiceai.org)
+To view the published documentation, visit [**https://docs.spiceai.org**](https://docs.spiceai.org).
 
-This repo contains the markdown files which generate the above website. See below for guidance on running with a local environment to contribute to the docs.
+To contribute to the documentation, follow the instructions below to set up a local development environment.
 
 ## Overview
 
 The Spice docs are built using [Docusaurus](https://docusaurus.io/) hosted on [GitHub Pages](https://pages.github.com/).
 
 The [website](./website) directory contains the Docusaurus project, markdown files, and theme configurations.
 
-## Pre-requisites
+## Prerequisites
 
-- [Node.js](https://nodejs.org/en/)
-- [Docusaurus](https://docusaurus.io/docs/installation)
+- [Node.js](https://nodejs.org/en/) (v18 or later recommended)
+- npm (included with Node.js)
+
+Docusaurus is installed as a project dependency and does not need to be installed globally.
 
 ## Environment setup
 
@@ -38,21 +40,34 @@ cd ./docs/website
 npm install
 ```
 
-## Run local server
+## Run Local Server
 
-1. Make sure you're still in the `website` directory
-2. Run
+1. Ensure you are in the `website` directory.
+2. Start the development server:
 
 ```sh
 npm start
 ```
 
-3. Navigate to `http://localhost:3000/`
+3. Open `http://localhost:3000/` in a browser. The local documentation site should appear, and changes to markdown files are reflected automatically.
+
+## Contributing to the Docs
+
+1. Fork this repository to your GitHub account.
+2. Clone your fork and create a new branch:
+
+   ```sh
+   git checkout -b my-docs-update
+   ```
+
+3. Make changes to the markdown files in `website/docs/`.
+4. Commit and push your changes:
 
-## Update docs
+   ```sh
+   git add .
+   git commit -m "docs: describe your change"
+   git push origin my-docs-update
+   ```
 
-1. Fork repo into your account
-1. Create new branch
-1. Commit and push changes to forked branch
-1. Submit pull request from downstream branch to the upstream branch for the correct version you are targeting
-1. Staging site will automatically get created and linked to PR to review and test
+5. Open a pull request from your branch to the `trunk` branch of the upstream repository.
+6. A staging site is automatically generated and linked in the pull request for review.

website/docs/cli/index.md

@@ -32,7 +32,14 @@ The Spice CLI can be installed by:
 
 The `spice` program will be added to the PATH automatically for **bash**, **fish**, and **zsh** shells.
 
-After installing the Spice CLI for the first time, ensure you've got the correct version by running `spice version`. The Runtime version is not expected to be shown, as the runtime will be downloaded and installed automatically upon first run.
+After installing the Spice CLI for the first time, verify the installation by running `spice version`. Expected output:
+
+```console
+CLI version:     1.x.x
+Runtime version: (not installed)
+```
+
+The runtime is downloaded and installed automatically upon first run of `spice run`.
 
 ## Getting started
 

website/docs/clients/index.md

@@ -2,11 +2,13 @@
 title: 'Clients and Tools'
 sidebar_label: 'Clients and Tools'
 sidebar_position: 10
-description: 'Client and tools'
+description: 'Client and tools for connecting to Spice'
 pagination_prev: null
 pagination_next: null
 ---
 
+Spice supports a variety of clients and tools for querying data, including SQL clients, BI tools, and programmatic interfaces. Use these integrations to connect applications and dashboards to the Spice runtime.
+
 import DocCardList from '@theme/DocCardList';
 
 <DocCardList />

website/docs/components/index.md

@@ -2,11 +2,13 @@
 title: 'Runtime Components'
 sidebar_label: 'Components'
 sidebar_position: 5
-description: Runtime components'
+description: 'Runtime components'
 pagination_prev: null
 pagination_next: null
 ---
 
+Spice runtime components are the building blocks for configuring data access, acceleration, AI models, embeddings, and secrets. Each component is defined in the `spicepod.yaml` manifest.
+
 import DocCardList from '@theme/DocCardList';
 
 <DocCardList />

website/docs/components/secret-stores/index.md

@@ -1,16 +1,16 @@
 ---
 title: 'Secret Stores'
 sidebar_label: 'Secret Stores'
-description: ''
+description: 'Configure secret stores to manage sensitive data like passwords, tokens, and API keys.'
 image: /img/og/secret-stores.png
 sidebar_position: 3
 pagination_prev: null
 pagination_next: null
 ---
 
-A Secret Store is a location where `secrets` are stored and can be used to store sensitive data, like passwords, tokens, and secret keys.
+A Secret Store is a secure location where secrets (such as passwords, tokens, and API keys) are stored. Spice retrieves secrets from configured stores at runtime and injects them into component parameters.
 
-Spice supports secret stores: [`env`](./env/index.md), [`kubernetes`](./kubernetes/index.md), [`keyring`](./keyring/index.md) and [`aws_secrets_manager`](./aws-secrets-manager/index.md). The `env` secret store is loaded by default.
+Supported secret stores include: [`env`](./env/index.md), [`kubernetes`](./kubernetes/index.md), [`keyring`](./keyring/index.md), and [`aws_secrets_manager`](./aws-secrets-manager/index.md). The `env` secret store is loaded by default.
 
 ### Default
 

website/docs/deployment/index.md

@@ -5,7 +5,7 @@ description: 'Deploy Spice.ai in your environment'
 sidebar_position: 11
 ---
 
-Learn how to deploy Spice.ai in your environment.
+Spice supports flexible deployment options ranging from a single binary to fully managed cloud deployments. Choose the architecture that best fits your application's latency, scale, and operational requirements.
 
 ## Deployment Architectures
 

website/docs/faq/index.md

@@ -41,7 +41,7 @@ Yes. Spice natively supports federated queries across disparate data sources wit
 
 ## 5. Is Spice a cache?
 
-Not solely. Spice functions as an active cache or working dataset prefetcher. Unlike traditional caches that fetch data reactively, Spice proactively prefetches and materializes data based on filters, intervals, triggers, or Change Data Capture (CDC), ensuring data readiness for queries. Spice also supports [results caching](/docs/features/caching).
+Not solely. Spice functions as an active cache or working dataset prefetcher. A _working dataset_ is a subset of data actively used by an application or model, such as recent records or frequently accessed tables. Unlike traditional caches that fetch data reactively, Spice proactively prefetches and materializes data based on filters, intervals, triggers, or Change Data Capture (CDC), ensuring data readiness for queries. Spice also supports [results caching](/docs/features/caching).
 
 ## 6. Is Spice a CDN for databases?
 

website/docs/features/cdc/index.md

@@ -7,7 +7,7 @@ pagination_prev: null
 pagination_next: null
 ---
 
-Change Data Capture (CDC) captures changed rows from a database's transaction log and delivers them to consumers with low latency. This technique enables Spice to keep [locally accelerated](../data-acceleration/index.md) datasets up-to-date in real time with the source data. It is efficient because it only transfers the changed rows instead of re-fetching the entire dataset.
+Change Data Capture (CDC) captures insert, update, and delete events from a database's transaction log and delivers them to consumers with low latency. This technique enables Spice to keep [locally accelerated](../data-acceleration/index.md) datasets synchronized with the source data in near real-time. CDC is efficient because it transfers only changed rows instead of re-fetching the entire dataset.
 
 ## Benefits
 

website/docs/features/data-acceleration/index.md

@@ -61,4 +61,18 @@ spice sql
 select * from taxi_trips;
 ```
 
+Example output:
+
+```
++---------------+--------------+------------------+
+| trip_distance | total_amount | tpep_pickup_time |
++---------------+--------------+------------------+
+| 1.2           | 9.80         | 2023-01-15 08:32 |
+| 3.4           | 18.50        | 2023-01-15 09:10 |
++---------------+--------------+------------------+
+Time: 0.012s. 2 rows.
+```
+
+Locally accelerated datasets provide significantly faster query times compared to remote sources.
+
 [Learn more about Data Accelerators](/docs/components/data-accelerators) for faster access.

website/docs/features/data-ingestion/index.md

@@ -10,10 +10,12 @@ tags:
   - write
 ---
 
-Data can be ingested by the Spice runtime into a Data Connector using the following methods:
+Data can be ingested into the Spice runtime using the following methods:
 
 1. **SQL Statements** – Write data directly to [write-capable connectors](/docs/tags/write) using standard SQL syntax.
-2. **OpenTelemetry (OTEL) Ingestion** – Stream OTEL data for real-time processing.
+2. **OpenTelemetry (OTEL) Ingestion** – Stream OTEL metrics for real-time processing and acceleration.
+
+Data ingestion is useful for scenarios such as collecting metrics from edge devices, writing application events for later analysis, or populating datasets from external sources.
 
 ## SQL Statements