doc-standard

Documentation Writing Standards

This standard constrains the writing style of youlai-admin-docs all sections. Goal: let readers quickly find code, copy and use it, without reading nonsense.

Core Principles

Readers come with a task and leave with code. The sole value of documentation is to let readers complete the task at hand as quickly as possible, not to showcase the author's knowledge system.

Code is for machines to execute, documentation is for people to understand. When writing documentation, first think: why did the reader open this page? What should they have in hand when they leave?

Documentation Classification Framework

Based on the Diátaxis framework, documentation is divided into four modes according to reader needs.One document does only one thing, mixing modes is the beginning of quality decline.

Mode	Reader Question	Corresponding Section
Tutorial	"Teach me how to do it step by step"	Operation Guide (interface operations), Development Guide (writing code)
Operation Guide	"Help me complete this task"	Advanced Customization
Reference	"What APIs does this component/function/configuration item have"	Component Documentation, Composable Documentation, System Settings, FAQ
Explanation	"What are the team conventions"	Code Standards

Operation guides do not mix in principles, reference documentation does not mix in tutorials. Cross-cutting topics use cross-references, not repetition.

Documentation Maintenance Principles

Draw on Google documentation best practices：

• Minimal viable documentation: A small amount of fresh and accurate documentation > a large amount of stale and broken documentation. Maintain continuously like pruning a bonsai
• Update with code: Documentation changes and code changes are in the same PR, without lag
• Delete dead documentation: Delete outdated, incorrect, and redundant documentation in a timely manner. Dead documentation is worse than no documentation—it misleads readers
• Eliminate duplication: Link rather than copy. The same information is defined in only one place, and other places cross-reference it
• Write for people to read: Do not write documentation for what code can express (naming, type signatures); documentation writes what code cannot express (intent, constraints, boundaries)

Prohibited Elements

The following elements must be deleted entirely, without exception:

Prohibited Item	Example	Why Prohibited
"What to read first?" navigation table	`	What you want to do | Recommended section |` the entire table
"Introduction" "Overview" purely descriptive paragraphs	"Internationalization capability covers language packs, runtime switching..." 5 bullets	Readers know what this is as soon as they click in, no need to introduce it again
"Feature Highlights" list	## 功能特性 + emoji bullet	Low information density, and it can already be seen in the outline
"Use Cases" paragraph	## 使用场景 or > 💡 使用场景：	Readers judge the scenario themselves; the author does not need to teach them. The exception is the introductory explanation of applicable scenarios at the start of advanced customization (recipes).
"Quick Summary" repeats the table of contents	## 快速摘要 lists the chapters again	Like "What to Read First," it is a repetition of the table of contents
ASCII architecture diagram	┌──┐│ │└──┘ box-drawing diagram	Hard to maintain, takes up space, misaligned on mobile; use Mermaid or a plain list
"Next Steps" and "Related Links" tail sections	## 下一步 / ## 相关链接 + 3–5 jump links	Readers will use search and the sidebar; they do not need the author's recommendations
Long "Implementation Principles" section	### 实现原理 + 50 lines of source code references	How-to guides should only cover "how to use it"; put principle-type content in a blog or a separate section
Emoji decoration	## 🎯 在线体验 / > 💡 提示：	Interferes with reading; do not use in formal documentation
"Source Code Location" list	## 源码位置 + 4 file paths	Readers will use the IDE's global search
Putting "FAQ" in the main text	## 常见问题 + 3–5 Q&As	FAQs should be centralized in the /faq/ section and not pollute the how-to documentation
"Summary" repeats the full text	## 总结 lists all the rules in the full text again	Like "Quick Summary," it is a repetition of the content
"References" list	## 参考来源 + 8 external links	The specification clauses themselves are the source; no bibliography is needed
"Why It Is Designed This Way" explanatory paragraph	"The reason for distinguishing it this way is..."	Specification documents give rules, not reasons
Blog-style transitional sentences	"Next, let us look at..." "Next, we will analyze in detail..."	Give the content directly; do not describe what you are about to do
Empty introductory remarks	"Learn how to build and deploy the project"	The title already states it; the introduction should provide incremental information

Allowed but restrained elements

Element	When to use	Restriction
One-sentence introduction	At the beginning of a chapter, state "what this is and what it can do"	No more than 2 lines; do not pile up feature adjectives
Mermaid flowchart	Truly complex flows (login, dynamic route generation)	Use only when a diagram is worth a thousand words; use a plain list for simple flows
Notes ::: tip	Real pitfalls (such as BOM, encoding, required fields)	No more than 1 per page; do not use for common-sense reminders
Table	Comparing configuration items, Props, parameters	Use only when "there are many fields and comparison is needed"

General structural constraints

All documentation must follow:

---
title: 页面标题
---

# 页面标题

一句话说明这页讲什么、读者能做什么。不超过 2 行。

## 章节一
（代码 + 必要说明，不写「实现原理」）

## 章节二
（同上）

Hard rules：

1. At the beginning of the file, title and # 标题must be consistent
2. After the one-sentence introduction, go directly into the chapters;do not insert "Introduction," "Overview," or "What to Read First"
3. Chapter titles should be written as "What it does / What it is", not "Principles," "Mechanism," or "Detailed Explanation"
4. Code blocks must have a language label (```typescript / ```vue), and TypeScript always uses the full name typescript, not the abbreviation ts
5. Code example values must be concrete (ref(1) not ref('')), with comments explaining the meaning of the values
6. At the end of the documentdo not addthe "Related Links", "Next Steps", "Source Code Location" tail
7. No emoji anywhere in the text (including correct/incorrect symbols in code comments)
8. When marking correct/incorrect in code comments, use words instead of symbols:// 推荐 / // 不推荐

Directory and naming conventions

• All directories and .md files use kebab-case (lowercase + hyphens)
• File names and title frontmatter remain semantically consistent
• Files with the same content must not coexist (e.g., index.md and introduction.md are duplicates)
• Legacy files are cleaned up promptly (old merged templates should be deleted)

Content ownership rules

When a topic spans two document types, assign it by the primary operation, and use a cross-reference in the other:

Cross-cutting topic	Owning document	Handling in the other document
Menu title internationalization	i18n.md	router-menu.md One sentence + link
Environment variables	settings.md	deploy.md reference
Nginx configuration	deploy.md	settings.md do not repeat
Button permissions and permission identifiers	permission.md	router-menu.md reference

Cross-reference format:详见[新增菜单](/element/guide/router-menu#菜单标题国际化), and do not create a separate "Related Links" section.

Section templates

The 7 section templates (How-to Guide, Development Guide, Project Deployment, Component Documentation, Composable Documentation, Advanced Customization, FAQ) define the structure, writing rules, and word count control for each type of document. See templates.md。