Polish website documentation copy for release

Author: xoofx

site/docs/benchmarks.md

@@ -17,7 +17,7 @@ The following tables summarize benchmark results as of `2026-02-10`.
 
 > [!WARNING]
 > 
-> These results should not be interpreted as an absolute ranking of libraries. The goal of these benchmarks was to make sure that `XenoAtom.Logging` is in the **right performance tier**, produces **zero allocations** and to track relative performance across versions as we optimize. Each library has different architectural trade-offs, so end-to-end call costs should be interpreted in the context of the specific benchmark scenarios and constraints.
+> Do not treat these results as an absolute ranking. The goal is to verify that `XenoAtom.Logging` stays in the right performance tier, remains zero-allocation on targeted paths, and tracks progress over time. Libraries make different architectural trade-offs, so interpret end-to-end costs within these benchmark constraints.
 
 ### Sync suite (`LoggingSyncBenchmarks`)
 
@@ -152,7 +152,7 @@ Preset suite names:
 
 Each category measures the same logical logging operation for each participating library.
 
-Benchmark classes use explicit `SimpleJob` settings to keep runs stable and avoid unbounded auto-scaling of operations per iteration.
+Benchmark classes use explicit `SimpleJob` settings to keep runs stable and avoid unbounded auto-scaling per iteration.
 
 ## Fairness strategy
 
@@ -162,10 +162,10 @@ To keep comparisons fair:
 - Each library is configured with an in-memory/no-op sink.
 - Enabled benchmarks still force each sink to consume the rendered message payload, so we measure logging + message materialization, not just level checks.
 - Disabled benchmarks use the same category names and thresholds across all libraries (`Bench.Enabled` and `Bench.Disabled`).
-- Async categories include only libraries with native asynchronous infrastructure and route payload lengths through an asynchronous consumer queue to compare call-site overhead under asynchronous sink pressure.
+- Async categories include only libraries with native asynchronous infrastructure and route payload lengths through an asynchronous consumer queue to compare call-site overhead under sink pressure.
 - Async consumer queues are bounded and drop on overflow to prevent unbounded memory growth from benchmark harness backpressure.
 
 ## Notes
 
-- Different libraries have different internal architectures (sync vs async pipelines, template handling, interpolation handlers, etc.); results should be interpreted as *end-to-end call cost under equivalent benchmark constraints*, not as an absolute universal ranking.
+- Different libraries use different architectures (sync vs async pipelines, template handling, interpolation handlers, etc.); interpret results as *end-to-end call cost under equivalent constraints*, not as a universal ranking.
 - Run benchmarks on an idle machine and repeat multiple times before drawing conclusions.

site/docs/getting-started.md

@@ -4,7 +4,7 @@ title: "Getting Started"
 
 # Getting Started
 
-This guide walks through a minimal setup, then shows the async and terminal variants.
+This guide starts with a minimal setup, then covers async mode and terminal output.
 
 ## 1. Install packages
 
@@ -49,13 +49,13 @@ LogManager.Shutdown();
 
 Key points:
 
-- `Initialize` defaults to sync processing.
-- `GetLogger("App")` creates/gets a logger category.
+- `Initialize` defaults to synchronous processing.
+- `GetLogger("App")` resolves a logger category.
 - `Shutdown()` flushes and disposes writers.
 
 ## 3. Switch to asynchronous processing
 
-When logging throughput is high, initialize for async:
+When throughput is high, initialize for async processing:
 
 ```csharp
 var config = new LogManagerConfig
@@ -81,8 +81,8 @@ LogManager.InitializeForAsync(config);
 
 `OverflowMode` behavior:
 
-- `Block` (default recommendation): preserve correctness, backpressure producers.
-- `Drop` / `DropAndNotify`: prioritize producer latency, allow loss.
+- `Block` (recommended default): preserve correctness and backpressure producers.
+- `Drop` / `DropAndNotify`: prioritize producer latency, but allow loss.
 - `Allocate`: temporarily exceed configured queue capacity.
 
 ## 4. Structured values and scopes

site/docs/log-formatter.md

@@ -6,24 +6,24 @@ title: "Log Formatters"
 
 `XenoAtom.Logging` formats a `LogMessage` into text using `LogFormatter` implementations.
 
-Key goals:
+Goals:
 
 - Zero allocations on the hot path.
 - Formatting into `Span<char>` (and optionally emitting segment metadata for styling).
 - User-defined text formats via source generation (`[LogFormatter]`).
 - Common formatter settings (`LevelFormat`, `TimestampFormat`) centralized on `LogFormatter`.
 
-This page covers the user-facing API and common customization patterns. For implementation-level details, see the internal formatter spec (`site/docs/specs/formatter_specs.md`).
+This page covers user-facing APIs and customization patterns. For implementation-level details, see the internal formatter spec (`site/docs/specs/formatter_specs.md`) in the repository.
 
 ## Built-in formatters
 
-The core package includes a few ready-to-use text formatters:
+The core package includes ready-to-use text formatters:
 
 - `StandardLogFormatter` (single line: timestamp, level, logger name, optional event id, message, optional exception)
 - `CompactLogFormatter` (time, level, message)
-- `DetailedLogFormatter` (like standard + thread id and a sequence id)
+- `DetailedLogFormatter` (like standard plus thread id and sequence id)
 
-There is also `JsonLogFormatter` which is not template-based and has different semantics (JSON lines for ingestion).
+`JsonLogFormatter` is also available. It is not template-based and targets JSON-line ingestion scenarios.
 
 ## Selecting a formatter
 
@@ -75,7 +75,7 @@ var terminalWriter = new TerminalLogWriter(Terminal.Instance)
 
 ## Runtime customization
 
-`LevelFormat` and `TimestampFormat` are inherited from `LogFormatter`. Template-generated formatters initialize these values in generated constructors, and you can still override them with `with { ... }`:
+`LevelFormat` and `TimestampFormat` are inherited from `LogFormatter`. Template-generated formatters initialize these values in generated constructors, and you can override them with `with { ... }`:
 
 ```csharp
 using XenoAtom.Logging;
@@ -88,7 +88,7 @@ var formatter = StandardLogFormatter.Instance with
 };
 ```
 
-Default `LevelFormat` is `Tri` (aligned 3-character levels like `INF`, `WRN`, `ERR`).
+The default `LevelFormat` is `Tri` (aligned 3-character levels such as `INF`, `WRN`, `ERR`).
 
 `TimestampFormat` defaults to `"yyyy-MM-dd HH:mm:ss.fffffff"` unless changed by the formatter template (for example `{Timestamp:HH:mm:ss}`).
 
@@ -113,7 +113,7 @@ var formatter = MyLogFormatter.Instance;
 
 ## Template syntax (user-facing)
 
-Formatter templates look like a .NET composite format string, but the generator validates the template at compile time and produces a specialized `TryFormat(...)` implementation.
+Formatter templates look like .NET composite format strings. The generator validates templates at compile time and emits a specialized `TryFormat(...)` implementation.
 
 ### Literals and escaping braces
 
@@ -162,7 +162,7 @@ Rules and behavior:
 - A conditional section starts with `{?` and ends with `?}`.
 - Conditional sections **cannot be nested**.
 - A conditional section must contain at least one field placeholder.
-- A conditional section is emitted only if **all emptyable fields referenced within the section are non-empty**.
+- A conditional section is emitted only if **all emptyable fields referenced in that section are non-empty**.
 - If a conditional contains no emptyable fields, the generator warns with `XLF0006` (it is always emitted).
 
 Emptyable fields are:
@@ -177,7 +177,7 @@ All other fields are always considered present.
 
 ### Supported fields and format specifiers
 
-Fields are case-insensitive and map to `LogMessage` data. This is a closed set.
+Fields are case-insensitive and map to `LogMessage` data. The set is closed.
 
 | Field | Meaning | Format (`:...`) |
 |---|---|---|
@@ -246,7 +246,7 @@ logger.InfoMarkup("[green]ready[/]");
 
 ## Segments and terminal styling
 
-Text formatters can optionally emit segment metadata (`LogMessageFormatSegments`) while formatting. This enables writers to style output by segment kind (timestamp/level/logger name, etc.).
+Text formatters can optionally emit segment metadata (`LogMessageFormatSegments`) while formatting. This lets writers style output by segment kind (timestamp/level/logger name, etc.).
 
 `TerminalLogWriter` uses these segment kinds to apply styles:
 
@@ -268,4 +268,4 @@ Common generator diagnostics:
 - `XLF0003`: invalid format specifier (e.g., `{Level:oops}` or `{Properties:sep=, }`).
 - `XLF0006`: conditional section is always emitted (no emptyable fields inside).
 
-If you are consuming NuGet packages and the generator does not run, ensure you are using the .NET 10 SDK and that analyzers are enabled in your build. If you are using project references and analyzers are not flowing, add an explicit analyzer reference to `XenoAtom.Logging.Generators.csproj`.
+If you consume NuGet packages and the generator does not run, verify that you use the .NET 10 SDK and analyzers are enabled. If you use project references and analyzers are not flowing, add an explicit analyzer reference to `XenoAtom.Logging.Generators.csproj`.

site/docs/microsoft-extensions-logging.md

@@ -9,7 +9,7 @@ This guide helps teams move from `Microsoft.Extensions.Logging` (MEL) patterns t
 ## Scope of compatibility
 
 `XenoAtom.Logging` is not a MEL provider/bridge today.  
-Migration is API-level: update application logging code and startup configuration.
+Migration is API-level: update startup configuration and logging call sites.
 
 ## Quick mapping
 
@@ -110,8 +110,8 @@ logger.Info(
 
 ## Async behavior differences
 
-MEL provider behavior depends on provider implementation.  
-XenoAtom.Logging has explicit async queue settings:
+MEL provider behavior depends on each provider implementation.  
+`XenoAtom.Logging` exposes explicit async queue settings:
 
 - `InitializeForAsync(config)`
 - `AsyncLogMessageQueueCapacity`
@@ -123,7 +123,7 @@ Use `Block` when correctness is more important than producer latency.
 ## Recommended migration strategy
 
 1. Introduce `LogManager` startup/shutdown lifecycle.
-2. Replace logger injection with `Logger` access (`LogManager.GetLogger(...)`) in app entry points/services.
+2. Replace logger injection with `Logger` access (`LogManager.GetLogger(...)`) at app entry points/services.
 3. Migrate high-traffic logs first to `[LogMethod]` or interpolated APIs.
 4. Move sinks to `FileLogWriter`/`JsonFileLogWriter`/`TerminalLogWriter` as needed.
 5. Validate throughput and behavior with [Benchmarks](benchmarks.md) and app-specific load tests.

site/docs/readme.md

@@ -4,13 +4,13 @@ title: "User Guide"
 
 # User Guide
 
-This guide gives you the practical map for using `XenoAtom.Logging` in production:
+This guide helps you adopt `XenoAtom.Logging` in production without getting overwhelmed:
 
-- start simple
-- choose sync or async behavior intentionally
-- add structure, sinks, and formatting progressively
+- Start with a minimal setup.
+- Choose sync or async behavior intentionally.
+- Add structure, sinks, and formatting incrementally.
 
-If you are new to the library, start with [Getting Started](getting-started.md).
+If you are new to the library, begin with [Getting Started](getting-started.md).
 
 ## Installation
 
@@ -81,9 +81,9 @@ logger.Info(
 
 ## Choosing sync vs async
 
-Use sync mode when latency is low and writes are predictable.
+Use sync mode when sink I/O is low latency and predictable.
 
-Use async mode when throughput is high or sink I/O can block:
+Use async mode when throughput is high or when sink I/O can block:
 
 ```csharp
 config.AsyncLogMessageQueueCapacity = 4096;
@@ -96,7 +96,7 @@ LogManager.InitializeForAsync(config);
 Overflow guidance:
 
 - `Block`: safest for correctness (recommended default for critical logs).
-- `Drop` / `DropAndNotify`: lower producer latency, allows loss.
+- `Drop` / `DropAndNotify`: lower producer latency, but allow loss.
 - `Allocate`: temporary queue growth under pressure.
 
 See [Shutdown Semantics](shutdown.md) and [Thread Safety](thread-safety.md) for operational behavior.

site/readme.md

@@ -10,21 +10,20 @@ og_type: website
       <span class="c64-text">XenoAtom.Logging</span>
     </h1>
     <p class="lead mt-3 mb-4">
-      A high-performance structured logging runtime for .NET.<br>
-      Zero-allocation hot path, predictable async throughput, and rich terminal/UI rendering.
+      High-performance structured logging for .NET.<br>
+      Zero-allocation hot path, predictable async behavior, and rich terminal/UI output.
     </p>
     <div class="d-flex justify-content-center gap-3 mt-4 flex-wrap">
       <a href="{{site.basepath}}/docs/getting-started/" class="btn btn-primary btn-lg"><i class="bi bi-rocket-takeoff"></i> Get started</a>
       <a href="{{site.basepath}}/docs/" class="btn btn-outline-light btn-lg"><i class="bi bi-book"></i> Browse docs</a>
       <a href="https://github.com/XenoAtom/XenoAtom.Logging/" class="btn btn-info btn-lg"><i class="bi bi-github"></i> GitHub</a>
     </div>
-
     <div class="row row-cols-1 row-cols-lg-2 gx-3 gy-3 mt-4 text-start mx-auto" style="max-width: 66rem;">
       <div class="col">
         <div class="card h-100">
           <div class="card-header h5"><i class="bi bi-box-seam xenoatom-feature-icon xenoatom-icon--input"></i>Core package</div>
           <div class="card-body">
-            <p class="mb-2">Install <code>XenoAtom.Logging</code> for the core runtime, async processing, formatters, and file/JSON writers.</p>
+            <p class="mb-2">Install <code>XenoAtom.Logging</code> for core runtime APIs, async processing, formatters, and file/JSON sinks.</p>
             <pre class="language-shell-session mb-0"><code>dotnet add package XenoAtom.Logging</code></pre>
           </div>
         </div>
@@ -33,15 +32,14 @@ og_type: website
         <div class="card h-100">
           <div class="card-header h5"><i class="bi bi-display xenoatom-feature-icon xenoatom-icon--controls"></i>Terminal package (optional)</div>
           <div class="card-body">
-            <p class="mb-2">Add <code>XenoAtom.Logging.Terminal</code> for markup logs, rich segment styling, and <code>LogControl</code> support powered by <a href="https://xenoatom.github.io/terminal">XenoAtom.Terminal.UI</a>.</p>
+            <p class="mb-2">Add <code>XenoAtom.Logging.Terminal</code> for markup logs, rich segment styling, and <code>LogControl</code> integration powered by <a href="https://xenoatom.github.io/terminal">XenoAtom.Terminal.UI</a>.</p>
             <pre class="language-shell-session mb-0"><code>dotnet add package XenoAtom.Logging.Terminal</code></pre>
           </div>
         </div>
       </div>
     </div>
-
     <div class="mt-4">
-      <p class="mb-2 text-white-50">Fullscreen <code>LogControl</code> demo (markup + structured logs + background producer):</p>
+      <p class="mb-2 text-white-50"><code>LogControl</code> demo (markup + structured logs + background producer):</p>
       <video class="terminal img-fluid" autoplay muted loop playsinline preload="metadata" aria-label="XenoAtom.Logging LogControl demonstration">
         <source src="{{site.basepath}}/img/xenoatom-logcontrol.webm" type="video/webm">
         <img class="terminal img-fluid" src="{{site.basepath}}/img/screenshot.png" alt="XenoAtom.Logging terminal screenshot">
@@ -57,7 +55,7 @@ og_type: website
       <div class="card h-100">
         <div class="card-header h4"><i class="bi bi-lightning-charge xenoatom-feature-icon xenoatom-icon--actions"></i> Zero-allocation hot path</div>
         <div class="card-body">
-          <p class="card-text mb-2">Interpolation handlers and generated logging methods minimize allocations in enabled logging paths.</p>
+          <p class="card-text mb-2">Interpolation handlers and generated logging methods minimize allocations on enabled logging paths.</p>
           <p class="mb-0"><a href="{{site.basepath}}/docs/benchmarks/">Performance benchmarks</a></p>
         </div>
       </div>
@@ -66,25 +64,25 @@ og_type: website
       <div class="card h-100">
         <div class="card-header h4"><i class="bi bi-cpu xenoatom-feature-icon xenoatom-icon--layout"></i> Sync-first, async when needed</div>
         <div class="card-body">
-          <p class="card-text mb-2">Use sync processing by default or switch to async with queue capacity and overflow policies (`Drop`, `Block`, `Allocate`).</p>
+          <p class="card-text mb-2">Use sync processing by default, or switch to async with explicit queue capacity and overflow policies.</p>
           <p class="mb-0"><a href="{{site.basepath}}/docs/getting-started/">Getting started guide</a></p>
         </div>
       </div>
     </div>
     <div class="col">
       <div class="card h-100">
-        <div class="card-header h4"><i class="bi bi-braces xenoatom-feature-icon xenoatom-icon--binding"></i> Structured + source-generated</div>
+        <div class="card-header h4"><i class="bi bi-braces xenoatom-feature-icon xenoatom-icon--binding"></i> Structured + generated APIs</div>
         <div class="card-body">
-          <p class="card-text mb-2">Log properties/scopes plus `[LogMethod]` and `[LogFormatter]` source generation for strongly-typed APIs.</p>
+          <p class="card-text mb-2">Use properties/scopes with `[LogMethod]` and `[LogFormatter]` generation for strongly typed APIs.</p>
           <p class="mb-0"><a href="{{site.basepath}}/docs/source-generator/">Source generator docs</a> · <a href="{{site.basepath}}/docs/log-formatter/">Formatter docs</a></p>
         </div>
       </div>
     </div>
     <div class="col">
       <div class="card h-100">
-        <div class="card-header h4"><i class="bi bi-file-earmark-text xenoatom-feature-icon xenoatom-icon--debug"></i> Production sinks</div>
+        <div class="card-header h4"><i class="bi bi-file-earmark-text xenoatom-feature-icon xenoatom-icon--debug"></i> Production-ready sinks</div>
         <div class="card-body">
-          <p class="card-text mb-2">File rolling, retention, failure handling, JSONL output, and runtime diagnostics for operations.</p>
+          <p class="card-text mb-2">File rolling, retention, failure handling, JSONL output, and runtime diagnostics.</p>
           <p class="mb-0"><a href="{{site.basepath}}/docs/file-writer/">File and JSON writers</a></p>
         </div>
       </div>
@@ -102,7 +100,7 @@ og_type: website
       <div class="card h-100">
         <div class="card-header h4"><i class="bi bi-arrow-left-right xenoatom-feature-icon xenoatom-icon--themes"></i> Migration guidance</div>
         <div class="card-body">
-          <p class="card-text mb-2">If you use <code>Microsoft.Extensions.Logging</code>, follow a practical migration path with equivalent patterns.</p>
+          <p class="card-text mb-2">If you use <code>Microsoft.Extensions.Logging</code>, follow a practical migration path to equivalent patterns.</p>
           <p class="mb-0"><a href="{{site.basepath}}/docs/microsoft-extensions-logging/">Migration from MEL</a></p>
         </div>
       </div>