Back to Details

md-style

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<!-- markdownlint-disable-file MD041 -->
<!-- markdownlint-disable-file MD041 -->

README Style Guide

README风格指南

Write concise, direct README files for experienced engineers.
为资深工程师编写简洁、直白的README文件。

Principles

原则

  • No fluff - Skip tables of contents, verbose explanations, development history
  • No roadmaps - Document current state only, not plans or decisions. Readme is an engineering specification. Not a project plan or changelog.
  • No repetition - Each fact appears once
  • No hype - Avoid "next generation", "production ready", "powerful", "comprehensive" and similar hyperbole
  • Direct voice - State facts, not opinions
  • No contrasting embellishments - Avoid like "not just a thing, it's a better thing", "not only a thing, it's something", "more than a"
  • 无冗余内容 - 跳过目录、冗长说明、开发历史
  • 无路线图 - 仅记录当前状态，不涉及计划或决策。README是工程规范，而非项目计划或变更日志。
  • 无重复 - 每个信息仅出现一次
  • 无夸大 - 避免使用“下一代”、“生产就绪”、“强大”、“全面”等类似夸张表述
  • 直接表述 - 陈述事实，而非观点
  • 无对比修饰 - 避免诸如“不只是一个工具，而是更好的工具”、“不仅是一个事物，更是某种创新”、“远超一个”这类表述

Structure

结构

Sections in order: Overview, Prerequisites, Usage, Architecture, Configuration, Testing, File Structure. One-line purpose statement at top under H1.
章节顺序：概述、前置条件、使用方法、架构、配置、测试、文件结构。在一级标题下方添加一行简短的用途说明。

Exclude

需排除内容

  • Tables of contents
  • Verbose troubleshooting guides
  • Development decisions/history
  • Future plans/roadmaps
  • Lengthy explanations of concepts
  • Multiple examples of similar things
  • 目录
  • 冗长的故障排查指南
  • 开发决策/历史
  • 未来计划/路线图
  • 冗长的概念解释
  • 同类内容的多个示例

Formatting

格式规范

  • Tables for structured data (components, variables, test coverage)
  • Code blocks for commands and examples
  • Bold for emphasis sparingly
  • No emojis unless explicitly requested
  • No emdashes
  • 使用表格展示结构化数据（组件、变量、测试覆盖率）
  • 使用代码块展示命令和示例
  • 谨慎使用粗体强调内容
  • 除非明确要求，否则不使用表情符号
  • 不使用破折号（emdashes）