Skip to main content

Nquiry Docs Voice & Style Mini-Guide

Created: 2026-05-03 (NQU-716) Status: v1, ratified by Joe in NQU-716 thread Note: This doc lives at docs/admin/ for now. When the NQU-714 IA reorganization lands, it moves to docs/reference/process/docs-voice-style-guide.md.

One question to ask before writing: who is reading this and what are they trying to do? The answer drives tone, depth, and word choice. This guide differentiates three docs audiences: end-user, licensee, and sales/prospect.

Universal principles (apply everywhere)​

  1. Plain language wins. Default to the simpler word. Reach for the precise technical term only when the precision matters; explain it inline the first time.
  2. Show, don't gesture. Concrete examples and screenshots over abstract description. "When the Finding badge is amber, treat the conclusion as a hypothesis" beats "uncertainty is communicated through visual indicators."
  3. No marketing voice in product docs. Words like seamless, robust, powerful, world-class, cutting-edge are noise. They make claims the reader can't verify and waste attention.
  4. Brand is Nquiry everywhere — always title-case in prose. Codebase identifier nquir is fine in code/paths. URLs are nquiry.ai. The nquir.ai legacy domain is being phased out per NQU-712.
  5. No emoji in product docs. Internal CD/CC comments and changelogs are fine; published docs aren't.

1. End-user audience (/guide/)​

Reader: investigative professional. Varied technical literacy — could be a federal investigator, corporate auditor, healthcare compliance lead. Cares about: getting their job done, knowing whether to trust the AI's output, finishing the report.

Voice principles​

  1. Action-oriented. Lead with the verb the user does. "Click Generate Analysis" not "The Generate Analysis button initiates analysis generation." (Imperative voice is the convention; second-person declarative — "You click..." — is also acceptable when imperative would feel curt.)
  2. Confidence-honest. When the AI's output requires interpretation (e.g., Finding badges, Quality metrics), say so plainly. Hedging language (may, could, sometimes) is appropriate — these readers prefer accurate uncertainty over false confidence.
  3. Investigative-domain literate. Readers know what evidence, finding, cited, gap analysis mean in their field. Use those words; don't translate to AI/ML jargon.
  4. No AI/ML jargon unless explained inline. Words like RAG, embedding, retrieval, prompt, context window, temperature should be replaced or explained on first use. "Retrieved evidence" → "evidence the AI surfaced from your collection."
  5. Screenshots over prose for UI explanations. A 200-word paragraph describing the analysis output is worse than a screenshot with three callouts.

DO / DON'T​

DODON'T
"Click any [E-014] citation marker to jump to the source evidence.""The citation reference token is hyperlinked to facilitate navigation to the underlying evidence document."
"When the Finding badge is amber (Possible), treat the conclusion as a hypothesis to verify.""Amber-state findings have probabilistic confidence below the established threshold."
"If the AI says 'evidence not found,' it means the AI didn't surface that evidence — not that it doesn't exist.""Negative retrieval results indicate retrieval-side absence, not corpus-side absence."
"Three things the AI checks in every analysis: faithfulness, coverage, and actionability.""The C1, C2, and C3 quality dimensions are evaluated against structured output schemas."
"Most analyses take 30–60 seconds. Some run longer when there are many evidence items.""Analysis latency exhibits a long tail correlated with corpus size."

Terminology preferences​

  • Investigation (not inquiry, despite the product name origin — investigation is the user-facing term)
  • Analysis (the AI-generated output the user reads)
  • Evidence (the documents/files in the user's collection)
  • Finding (a conclusion the AI surfaces, paired with confidence)
  • Citation marker (the [E-014]-style links)
  • Theme map (the visualization)
  • Quality metric (the AI's self-assessment of the write-up)
  • Avoid: RAG, embedding, retrieval pipeline, prompt, context, token

2. Licensee audience (/licensee/)​

Reader: cloud architect, security engineer, IT director, or DevOps lead at a customer org evaluating or operating a deployed Nquiry instance. AWS-literate. Cares about: prerequisites, security posture, operational footprint, total cost of ownership, what breaks.

Voice principles​

  1. Precise, technical, complete. Bullet-friendly. Tables for matrices. Code blocks for commands and config. Acceptable to assume AWS literacy (IAM, VPC, KMS, CloudTrail are not explained).
  2. Compliance-grade specificity. Federal/healthcare/regulated readers will scrutinize. Cite specific service names, regions, ARNs, IAM action names. Vague claims fail security review.
  3. No marketing language whatsoever. This audience tunes it out. "Robust security posture" → exact list of WAFv2 managed rule sets enabled.
  4. Acknowledge boundaries explicitly. "GovCloud is on the roadmap; not supported at GA" is better than not mentioning GovCloud at all. Hidden gotchas erode trust.
  5. Operationally honest. If a procedure has a 30-minute downtime window, say so. If RTO is 2 hours, say so. Underpromise, overdeliver.

Acronym convention for this audience​

This audience is technical enough that requiring expansion of every common AWS acronym (IAM, KMS, CMK, ARN, VPC, ACM, ALB, ECS) is over-cautious and noise-generating. Default: assume AWS literacy. Exception: less-common or product-specific acronyms (e.g., NIST FIPS 140-3, ATO, IL2/IL4) get a one-clause expansion on first use within a doc.

DO / DON'T​

DODON'T
"ECS Fargate 1 vCPU / 2 GB, 4 tasks across 2 AZs. Estimated monthly AWS spend: ~$2,400–3,200.""Production-grade compute infrastructure with auto-scaling for predictable performance."
"GovCloud (us-gov-west-1): not supported at GA. Tracked for prioritization on customer commitment — see NQU-412.""GovCloud capabilities are part of our forward-looking roadmap."
"Customer-managed CMK ARN passed via Terraform variable. Otherwise installer creates a fresh CMK with annual rotation enabled.""Encryption keys are managed flexibly to suit your compliance posture."
"RTO 2 hours, RPO 24 hours. Snapshot copy to customer-controlled S3 bucket optional.""Industry-leading disaster recovery."
"AWS WAFv2 Web ACL with: Core Rule Set, Known Bad Inputs, IP Reputation, Rate-based (2000 req/5min/IP).""Comprehensive web application protection."

Terminology preferences​

  • Customer (the licensee's organization) and deployer (the human doing the install) — distinguish where it matters
  • Licensed deployment (not self-hosted, on-prem — those carry baggage and aren't accurate)
  • In your AWS account (preferred over your environment)
  • Boundary inheritance (specifically — describes the FedRAMP authorization model)
  • Single-tenant per-customer (the deployment model)
  • Avoid: seamless integration, enterprise-grade, world-class, industry-leading, robust, comprehensive

3. Sales / prospect audience (/about/)​

Reader: discovery-stage prospect. Hasn't bought, may not have seen a demo. Cares about: does this solve my problem, what does it actually do, what's it cost, what are the limits.

Voice principles​

  1. Confident, capability-forward, honest about boundaries. "Nquiry analyzes investigative evidence to surface findings with citations" is better than "Nquiry empowers organizations to unlock investigative insights at scale."
  2. No false urgency, no scarcity language. "Limited beta" or "early access" is acceptable when literally true; "act now before X" is not.
  3. Claim only what's true today. Roadmap items are flagged as roadmap. Aspirations are not framed as capabilities.
  4. Specific over generic. "Nquiry handles document collections up to 500 evidence items in a single investigation" beats "scales to enterprise needs."
  5. Differentiate by mechanism, not adjective. Why Nquiry's analysis is trustworthy — citation traceability, quality self-checks, evidence-bounded retrieval — beats that it's trustworthy.

Drop AI-powered from sales surfaces (ratified)​

The phrase AI-powered is no longer differentiating — every product in the category claims it, and prospects skim past it. Replace with the specific mechanism (cited findings, evidence-bounded analysis, quality self-checks) or with the user benefit (verifiable conclusions, defensible reports). This applies to all sales/prospect-facing surfaces under /about/, the landing page, and sales decks.

DO / DON'T​

DODON'T
"Nquiry analyzes investigative evidence and produces findings paired with cited evidence so you can verify each claim.""Nquiry empowers investigators with AI-driven insights."
"Currently supports text documents (PDF, DOCX, TXT) and images. Audio/video transcription is on the roadmap.""Comprehensive multi-modal evidence support."
"Built for federal oversight, healthcare compliance, and corporate audit teams — domains where every claim must be defensible.""Built for the modern enterprise."
"Each analysis cites the specific evidence behind every claim. No black-box conclusions.""Industry-leading explainability."
"Available as SaaS at app.nquiry.ai or as a licensed deployment in your AWS account.""Flexible deployment options to suit any organization."

Terminology preferences​

  • Nquiry (always title case; never nquir in body text)
  • Investigation (not case or project in sales context — even though the data model calls it investigation/inquiry)
  • Evidence (plural collective; not documents — evidence signals the investigative domain)
  • Finding / cited finding (not insight — insight is marketing-flavored and dilutes the investigative framing)
  • Licensed deployment (the customer-deployed model — preferred over self-hosted, on-prem, private deployment)
  • Avoid: AI-powered, transformative, game-changing, next-generation, seamless, empower, unlock

Cross-audience checklist​

Before publishing any doc:

  • Audience clearly identifiable from the first paragraph
  • Tone matches the audience's voice principles
  • No marketing-flavored adjectives in product docs (/guide/, /admin/, /licensee/)
  • Capability claims match what's true today (or flagged as roadmap)
  • Brand is Nquiry (title case) in prose
  • No emoji in published content
  • First-occurrence acronyms are expanded (with the licensee-audience exception above for common AWS acronyms)

Update protocol​

This guide is reviewed:

  • When a new audience surface is added (e.g., a partner or developer-portal section)
  • When a strong piece of brand-voice work lands externally (sales playbook, press kit)
  • On the freshness sweep cadence (NQU-670)

Substantive changes are reviewed by Joe before merging. Spelling and minor consistency fixes go through standard PR review.