Add consolidated best-practices guidance for ValueStringBuilder

[Copilot]

The docs covered ValueStringBuilder features and limitations, but the operational guidance was fragmented across multiple pages. This updates the documentation to give both new and advanced users a single place to find the main pitfalls, safe defaults, and performance-oriented usage patterns.

• What changed

  • Added a dedicated Best practices and pitfalls article that consolidates the main usage guidance.
  • Linked the new guidance from Getting started, Advanced usage, and Known limitations.
  • Updated the docs navigation so the guidance is discoverable early instead of being buried across multiple pages.

• Guidance now covered explicitly

  • Safe default usage with using var stringBuilder = new ValueStringBuilder();
  • When to use the default constructor vs stackalloc vs the capacity constructor
  • Why AsSpan() should be preferred over ToString() when a string is not required
  • Why helpers should take the builder by ref
  • Where ValueStringBuilder is a poor fit (async, closures/lambdas, escaping stack-backed state)
  • The AppendFormat limitation around custom format components such as {0:00} and the preferred alternatives

• Docs structure

  • New article: docs/site/articles/best_practices.md
  • Cross-links added from the starter and advanced docs so the guidance supports both onboarding and deeper optimization work

Span<char> buffer = stackalloc char[64];
using var stringBuilder = new ValueStringBuilder(buffer);

stringBuilder.Append("ID-");
stringBuilder.Append(42, "D5");

ReadOnlySpan<char> value = stringBuilder.AsSpan();

[Copilot]

🟡 Changes recommended

Address the pooled-array leak and the two documentation corrections.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Consolidates ValueStringBuilder guidance into a discoverable best-practices article and links it from existing documentation.

Changes:

• Adds guidance on construction, disposal, spans, lifetimes, and formatting.
• Links the guidance from onboarding, advanced usage, and limitations pages.
• Adds the article to documentation navigation.

File summaries

File	Summary
docs/site/articles/toc.yml	Adds the best-practices navigation entry.
docs/site/articles/known_limitations.md	Adds a cross-link; typo correction needed (nit, 3 votes).
docs/site/articles/getting_started.md	Adds recommended defaults and a cross-link.
docs/site/articles/best_practices.md	Adds consolidated guidance. A moderate issue (3 votes) requires disposing the builder or increasing the buffer to avoid an ArrayPool leak; a lifetime clarification is also needed (nit, 3 votes).
docs/site/articles/advanced_usage.md	Adds a cross-link to the best-practices guidance.

Review details

• Files reviewed: 5/5 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.