Finish getting started page

docfx.json

@@ -4,7 +4,9 @@
     "content": [
       {
         "files": [
-          "**/*.{md,yml}"
+          "index.md",
+          "toc.yml",
+          "docs/**/*.{md,yml}"
         ],
         "exclude": [
           "_site/**"

docs/basic-usage.md

@@ -0,0 +1,7 @@
+# Basic Usage
+
+Documentation is in active development; and this page is next. Until it is more complete, the flow is very similar to [BitBadger.Documents](https://bitbadger.solutions/open-source/relational-documents/dotnet/basic-usage.html), the .NET implementation of a similar library. This library also supports `Json` in place of `Find` to return raw JSON, and `Json.write*` to write that JSON to a `PrintWriter`, bypassing the entire deserialize-from-the-database, serialize-to-the-output-body process.)
+
+## Examples
+
+Each library has an exhaustive suite of integration tests; reviewing those may also provide insight into the patterns used for effective document storage and retrieval.

docs/getting-started.md

@@ -78,27 +78,47 @@ Any of the [KotlinX Json][kx-json] properties can be set on the `options` proper
 > [!NOTE]
 > If you want to customize the document's `id` field, this needs be done before tables are created.
 
-The final step to being able to store and retrieve documents is to define one or more tables for them.
+The final step to being able to store and retrieve documents is to define one or more tables for them. The `Definition` class (in the `.java`, `.scala`, or `.kotlinx` packages) provides an `ensureTable` method that creates both a table and its ID index if that table does not already exist. (`ensureTable` is also a `Connection` extension method.)
 
-// TODO: stopped here
+To create a document table named `hotel` in Java...
 
-## Previous Instructions
+```java
+// Function that creates its own connection
+Definition.ensureTable("hotel");
+// ...or, on a connection variable named "conn"
+conn.ensureTable("hotel");
+```
 
-The exceedingly quick version:
+> [!NOTE]
+> Most operations could throw `DocumentException`, which is a checked exception. Java consumers must catch or declare it; for other languages, "must" becomes "should consider".
 
-- Add the desired module/package to your dependencies
-- Implement an instance of the `DocumentSerializer` interface and assign it to the `DocumentConfig.serializer` property (for all but kotlinx)
-- Set a PostgreSQL or SQLite JDBC connection string for the `Configuration.connectionString` property
+The repeatable nature of this call means that your application can run through a set of `ensureTable` calls at startup.
 
-At this point, `Connection.dbConn()` will provide a connection which can be used either for function calls or extension method calls. You will also be able to call functions without providing a connection, and the library will create one for that command. (Database pooling will help reduce connection overhead when using this technique.)
+### Indexing Documents
 
-From there, `Definition.ensureTable(name)` will create a table, and you are ready to start manipulating documents!
+Both PostgreSQL and SQLite support indexing individual fields in the document, just as they can index columns in a relational table. `Definition` provides the `ensureFieldIndex` method to establish these indexes. These functions take a table name, an index name, and a collection of field names from the document which should be indexed.
 
-(Documentation is in active development; until it is more complete, the flow is very similar to [BitBadger.Documents](https://bitbadger.solutions/open-source/relational-documents/dotnet/basic-usage.html), the .NET implementation of a similar library. This library also supports `Json` in place of `Find` to return raw JSON, and `Json.write*` to write that JSON to a `PrintWriter`, bypassing the entire deserialize-from-the-database, serialize-to-the-output-body process.)
+For example, imagine we had a `user` document, but we allow users to sign in via their e-mail address. In Java, this may look something like...
 
-## Examples
+```java
+// Create an index named idx_user_email on the user table
+Definition.ensureFieldIndex("user", "email", List.of("email"));
+```
 
-Each library has an exhaustive suite of integration tests; reviewing those may also provide insight into the patterns used for effective document storage and retrieval.
+Multiple-field indexes are also possible.
+
+For PostgreSQL, they provide a <abbr title="Generalized Inverted Index">GIN</abbr> index which can index the entire document. This index can be a full document index, which can be used for both containment queries or JSON Path matching queries, or one that is optimized for JSON Path operations. This library has a `DocumentIndex` enum with values `Full` and `Optimized` to specify which type of index is required. `ensureDocumentIndex` creates the index.
+
+```java
+// This index will be named idx_user_doc and is suitable for any operation
+Definition.ensureDocumentIndex("user", DocumentIndex.Full);
+```
+
+Indexes are not as important an up-front decision as some other aspects; nothing prevents a developer from adding an index when they realize they may need one.
+
+---
+
+We have access to a data store, we know how to create documents, and we have a place to store them. Now, it's time to use all that!
 
 
 [env]: https://docs.oracle.com/javase/tutorial/essential/environment/env.html "Environment Variables &bull; The Java Tutorials"

docs/toc.yml

@@ -1,2 +1,4 @@
 - name: Getting Started
   href: getting-started.md
+- name: Basic Usage
+  href: basic-usage.md

index.md

@@ -42,7 +42,7 @@ This module utilizes [`kotlix.serialization`][kotlinx] for its serialization and
 
 ## Talk about Them
 
-Bit Badger Solutions' Git is not set up for account registration _(yet! -- Homer Simpson)_. However, the author can be reached as `@Bit_Badger` on Twitter, `daniel@fedi.summershome.org` on the Fediverse, or via e-mail as `daniel` at the parent domain to this site's domain. This project is open to the public, so you will be able to track the progress of any issues you may report. 
+Bit Badger Solutions Git is not set up for account registration _(yet! -- Homer Simpson)_. However, the author can be reached as `@Bit_Badger` on Twitter, `daniel@fedi.summershome.org` on the Fediverse, or via e-mail as `daniel` at the parent domain to this site's domain. This project is open to the public, so you will be able to track the progress of any issues you may report. 
 
 
 [core-badge]: https://img.shields.io/maven-central/v/solutions.bitbadger.documents/core