跳到主要内容

V2 Docs Voice

This file defines the voice standard for the v2 documentation.

The goal is not to make every page sound identical. The goal is to make the whole documentation feel like it comes from the same mind.

Core Standard​

The voice should be:

  • clear
  • grounded
  • non-moralizing
  • conceptually precise
  • readable by an everyday person
  • calm and authoritative
  • prose-led by default

The reader should feel:

  • respected
  • oriented
  • informed

not:

  • judged
  • managed
  • lectured
  • impressed by jargon

What The Docs Are Trying To Do​

The docs exist to give the reader a framework for engineering the conditions that make discipline possible.

That means the writing should do more than define ideas. It should help the reader understand:

  • what the concept means
  • why it matters
  • how it connects to the framework
  • what it changes in practice

What The Voice Should Avoid​

  • moral pressure
  • motivational clichés
  • empty inspiration
  • generic self-help language
  • academic posturing
  • performative technicality
  • unexplained jargon
  • identity judgments disguised as advice
  • listicle-shaped writing as the default page structure

Avoid phrases that sound like:

  • "you just need to"
  • "the key is to stay disciplined"
  • "successful people always"
  • "if you really wanted it"
  • "this proves you are"

The Reader Model​

The reader is assumed to be intelligent.

They do not need to be talked down to. They also do not need to know the internal history of the framework.

The docs should stand on their own. They should not rely on phrases like:

  • "the book says"
  • "the talk explains"
  • "the source of truth is"

Those may matter for authoring, but not for reader-facing explanation.

Function-Specific Variation​

The voice stays consistent, but page types can shift slightly in emphasis.

Core Concepts​

  • tighter
  • cleaner
  • definition-first
  • less expansive

Framework Pages​

  • more explanatory
  • mechanism-oriented
  • connects concepts together

Tactical Guides​

  • more contextual
  • more practical
  • still framework-led, not generic advice

Reference Pages​

  • shorter
  • more direct
  • optimized for lookup

Tone Rules​

  • Prefer direct explanation over flourish.
  • Let paragraphs carry the argument.
  • Use lists to support orientation, comparison, or reference, not as the dominant shape of a page.
  • When a list is doing classification, use bolded category labels to improve scan speed.
  • Use plain language when possible.
  • Keep the thesis intact while lowering the cognitive cost of reading.
  • Be serious without becoming heavy.
  • Be warm through clarity, not through reassurance language.
  • Bring in scientific grounding when it clarifies a mechanism or meaningfully deepens understanding, not as decoration.

Final Check​

Before treating a page as aligned, ask:

  • Does this sound like one coherent authorial mind?
  • Is it clear without being simplistic?
  • Is it precise without becoming academic?
  • Does it avoid shame and moral pressure?
  • Does it help the reader build with the framework?
最后于 更新