docs: Audit and improve documentation

ARCHITECTURE.md

@@ -0,0 +1,49 @@
+# Architecture
+
+This document provides a high-level overview of the Poindexter library's architecture.
+
+## System Overview
+
+Poindexter is a Go library that provides a collection of utility functions, with a primary focus on sorting algorithms and a K-D tree implementation for nearest neighbor searches. The library is designed to be modular, with distinct components for different functionalities.
+
+The main components of the Poindexter library are:
+
+- **Sorting Utilities:** A set of functions for sorting slices of various data types, including integers, strings, and floats. It also provides generic functions for custom sorting.
+- **K-D Tree:** A K-D tree implementation for efficient nearest neighbor searches in a multi-dimensional space.
+- **WASM Build:** A WebAssembly build that allows the K-D tree to be used in browser environments.
+
+## Component Diagram
+
+The following diagram illustrates the high-level components of the Poindexter library and their relationships:
+
+```mermaid
+graph TD
+    subgraph Core Library
+        A[Sorting Utilities]
+        B[K-D Tree]
+    end
+
+    subgraph Browser Environment
+        C[WASM Build]
+    end
+
+    subgraph Go Application
+        D[Go Application]
+    end
+
+    D --> A
+    D --> B
+    C --> B
+
+    style A fill:#f9f,stroke:#333,stroke-width:2px
+    style B fill:#f9f,stroke:#333,stroke-width:2px
+    style C fill:#ccf,stroke:#333,stroke-width:2px
+    style D fill:#cfc,stroke:#333,stroke-width:2px
+```
+
+### Components
+
+- **Sorting Utilities:** This component contains all the sorting-related functions. It is used by Go applications that need to perform sorting operations.
+- **K-D Tree:** This component provides the K-D tree implementation. It is used by Go applications and is also the core component exposed in the WASM build.
+- **WASM Build:** This component is a wrapper around the K-D tree that compiles it to WebAssembly, allowing it to be used in web browsers.
+- **Go Application:** Any Go application that imports the Poindexter library to use its sorting or K-D tree functionalities.

AUDIT-DOCUMENTATION.md

@@ -0,0 +1,69 @@
+# Documentation Audit Report
+
+This document outlines the findings of a comprehensive audit of the Poindexter project's documentation. The audit assesses the completeness and quality of the documentation across several categories.
+
+## 1. README Assessment
+
+The `README.md` file is comprehensive and well-structured.
+
+- **Project Description:** Clear and concise.
+- **Quick Start:** Excellent, with runnable examples.
+- **Installation:** Clear `go get` instructions.
+- **Configuration:** N/A (no environment variables).
+- **Examples:** Well-documented with links to the `examples` directory.
+- **Badges:** Comprehensive (CI, coverage, version, etc.).
+
+**Conclusion:** The README is in excellent shape.
+
+## 2. Code Documentation
+
+The inline code documentation for public APIs is of high quality.
+
+- **Function Docs:** Public APIs in `poindexter.go` and `kdtree.go` are well-documented.
+- **Parameter Types:** All parameter types are clearly documented.
+- **Return Values:** Return values are documented.
+- **Examples:** `pkg.go.dev` examples are present and helpful.
+- **Outdated Docs:** No outdated documentation was identified.
+
+**Conclusion:** The code-level documentation is excellent.
+
+## 3. Architecture Documentation
+
+This is an area with significant room for improvement.
+
+- **System Overview:** A dedicated high-level architecture document is missing.
+- **Data Flow:** There is no specific documentation on data flow.
+- **Component Diagram:** No visual representation of components is available.
+- **Decision Records:** No Architectural Decision Records (ADRs) were found.
+
+**Conclusion:** The project would benefit from a dedicated architecture document.
+
+## 4. Developer Documentation
+
+The developer documentation is sufficient for new contributors.
+
+- **Contributing Guide:** `CONTRIBUTING.md` is present and covers the essential.
+- **Development Setup:** Covered in `CONTRIBUTING.md`.
+- **Testing Guide:** Covered in the `Makefile` section of the `README.md` and `CONTRIBUTING.md`.
+- **Code Style:** Mentioned in `CONTRIBUTING.md`.
+
+**Conclusion:** Developer documentation is adequate.
+
+## 5. User Documentation
+
+The user documentation is good but could be improved by adding dedicated sections for common issues.
+
+- **User Guide:** The `docs` directory serves as a good user guide.
+- **FAQ:** A dedicated FAQ section is missing.
+- **Troubleshooting:** A dedicated troubleshooting guide is missing.
+- **Changelog:** `CHANGELOG.md` is present and well-maintained.
+
+**Conclusion:** The user documentation is strong but could be enhanced with FAQ and troubleshooting guides.
+
+## Summary of Documentation Gaps
+
+Based on this audit, the following gaps have been identified:
+
+1.  **Architecture Documentation:** The project lacks a formal architecture document. A high-level overview with a component diagram would be beneficial for new contributors.
+2.  **FAQ:** A frequently asked questions page would help users quickly find answers to common problems without needing to create an issue.
+3.  **Troubleshooting Guide:** A dedicated guide for troubleshooting common issues would be a valuable resource for users, providing clear steps for resolution.

docs/FAQ.md

@@ -0,0 +1,41 @@
+# Frequently Asked Questions (FAQ)
+
+This page answers common questions about the Poindexter library.
+
+## General
+
+### What is Poindexter?
+
+Poindexter is a Go library that provides a collection of utility functions, including sorting algorithms and a K-D tree implementation for nearest neighbor searches.
+
+### What is the license?
+
+Poindexter is licensed under the European Union Public Licence v1.2 (EUPL-1.2). See the [LICENSE](LICENSE) file for more details.
+
+## K-D Tree
+
+### What is a K-D tree?
+
+A K-D tree is a data structure used for organizing points in a k-dimensional space. It is particularly useful for nearest neighbor searches.
+
+### How do I choose a distance metric?
+
+The choice of distance metric depends on your specific use case. Here are some general guidelines:
+
+-   **Euclidean (L2):** A good default for most cases.
+-   **Manhattan (L1):** Useful when movement is restricted to a grid.
+-   **Chebyshev (L∞):** Useful for cases where the maximum difference between coordinates is the most important factor.
+
+### Is the K-D tree thread-safe?
+
+The K-D tree implementation is not safe for concurrent mutations. If you need to use it in a concurrent environment, you should protect it with a mutex or share immutable snapshots for read-mostly workloads.
+
+## WASM
+
+### Can I use Poindexter in the browser?
+
+Yes, Poindexter provides a WebAssembly (WASM) build that allows you to use the K-D tree in browser environments. See the [WASM documentation](wasm.md) for more details.
+
+### What is the performance of the WASM build?
+
+The performance of the WASM build is generally good, but it will be slower than the native Go implementation. For performance-critical applications, it is recommended to benchmark your specific use case.

docs/TROUBLESHOOTING.md

@@ -0,0 +1,39 @@
+# Troubleshooting Guide
+
+This guide provides solutions to common problems you may encounter when using the Poindexter library.
+
+## General
+
+### `go get` command fails
+
+If you are having trouble installing the library with `go get`, make sure you have a working Go environment and that you have network connectivity. You can check your Go installation by running `go version`.
+
+## K-D Tree
+
+### `ErrDimMismatch` error when building a K-D tree
+
+This error occurs when the points you are using to build the K-D tree have inconsistent dimensions. Make sure that all points have the same number of coordinates.
+
+### `ErrDuplicateID` error when building a K-D tree
+
+This error occurs when you are using points with duplicate IDs. If you are using IDs, they must be unique for each point.
+
+### Nearest neighbor search is slow
+
+The K-D tree is designed for efficient nearest neighbor searches, but its performance can be affected by the distribution of your data. If you are experiencing slow performance, consider the following:
+
+-   **Data Distribution:** The K-D tree performs best with uniformly distributed data. If your data is highly clustered, the performance may be degraded.
+-   **Dimensionality:** The performance of the K-D tree can degrade as the number of dimensions increases. For very high-dimensional data, other methods may be more appropriate.
+
+## WASM
+
+### WASM module fails to load
+
+If the WASM module is not loading, make sure that the `.wasm` file is being served correctly and that the path to the file is correct in your HTML. You can check the browser's developer console for any errors related to loading the module.
+
+### Performance is slow in the browser
+
+The WASM build will generally be slower than the native Go implementation. If you are experiencing performance issues, consider the following:
+
+-   **Data Size:** The amount of data you are processing can affect performance. Try to minimize the amount of data you are sending to the WASM module.
+-   **Benchmarking:** Benchmark your specific use case to identify any performance bottlenecks.