Back to Details

readme-craft

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

README Craft

README 编写指南

Audience: Developers creating or improving project documentation.
Goal: Generate README files that convert scanners into users within 60 seconds.
受众： 正在创建或优化项目文档的开发者。
目标： 编写能在60秒内将浏览者转化为用户的README文件。

Core Philosophy

核心理念

A README is a sales pitch, onboarding guide, AND reference manual. Lead with value, prove with examples, document with precision.
README既是销售说辞、入门指南，也是参考手册。以价值为导向，用示例佐证，精准记录内容。

Common Failures

常见误区及修复方案

FailureFix
Installation firstLead with TL;DR and value prop
Describes what it ISDescribe what problem it SOLVES
No examplesOne example per feature minimum
Hidden limitationsDedicated limitations section
Single install methodThree+ pathways (curl, package manager, source)
No troubleshootingDocument top 5 common errors
误区修复方案
先讲安装步骤先展示TL;DR（摘要）和价值主张
描述工具本身说明工具解决的问题
无示例内容每个功能至少配一个示例
隐藏局限性增设专门的局限性板块
仅提供一种安装方式提供三种及以上途径（curl、包管理器、源码编译）
无故障排查内容记录Top5常见错误

Golden Structure

黄金结构

Tier 1: Hero Section

第一层：标题区

markdown
<p align="center">
  <img src="logo.png" width="200" alt="Project Name">
</p>

<p align="center">
  <a href="..."><img src="https://img.shields.io/..." alt="CI"></a>
  <a href="..."><img src="https://img.shields.io/..." alt="Version"></a>
  <a href="..."><img src="https://img.shields.io/..." alt="License"></a>
</p>

<p align="center">
  <b>One-line description of what problem this solves</b>
</p>

```bash
curl -sSL https://example.com/install.sh | bash
undefined
markdown
<p align="center">
  <img src="logo.png" width="200" alt="Project Name">
</p>

<p align="center">
  <a href="..."><img src="https://img.shields.io/..." alt="CI"></a>
  <a href="..."><img src="https://img.shields.io/..." alt="Version"></a>
  <a href="..."><img src="https://img.shields.io/..." alt="License"></a>
</p>

<p align="center">
  <b>一句话说明工具解决的问题</b>
</p>

```bash
curl -sSL https://example.com/install.sh | bash
undefined

Tier 2: TL;DR

第二层：TL;DR（摘要）

markdown
undefined
markdown
undefined

TL;DR

TL;DR

Problem: [Specific pain point users face]
Solution: [How this tool solves it]
FeatureBenefit
Feature 1Quantified benefit
Feature 2Quantified benefit
Feature 3Quantified benefit
undefined
问题： [用户面临的具体痛点]
解决方案： [该工具的解决方式]
功能收益
功能1可量化的收益
功能2可量化的收益
功能3可量化的收益
undefined

Tier 3: Quick Example

第三层：快速入门示例

markdown
undefined
markdown
undefined

Quick Start

快速入门

1. Install

1. 安装

curl -sSL https://example.com/install.sh | bash
curl -sSL https://example.com/install.sh | bash

2. Initialize

2. 初始化

mytool init
mytool init

3. Run core workflow

3. 运行核心流程

mytool process input.txt --output result.json
mytool process input.txt --output result.json

4. Verify

4. 验证

mytool status

**Rule:** 5-10 commands demonstrating the core workflow.
mytool status

**规则：** 用5-10条命令展示核心工作流程。

Tier 4: Reference Sections

第四层：参考板块

  • Philosophy/Design decisions
  • Alternatives comparison
  • Installation (multiple methods)
  • Command reference
  • Configuration options
  • Architecture (for complex systems)
  • 设计理念/决策依据
  • 竞品对比
  • 安装方式（多种途径）
  • 命令参考
  • 配置选项
  • 架构说明（针对复杂系统）

Tier 5: Support Sections

第五层：支持板块

  • Troubleshooting
  • Limitations
  • FAQ
  • Contributing
  • License
  • 故障排查
  • 局限性说明
  • 常见问题（FAQ）
  • 贡献指南
  • 许可证

Section Templates

板块模板

Comparison Table

竞品对比表格

markdown
undefined
markdown
undefined

Why [Tool] Over Alternatives?

为何选择[工具]而非竞品？

Feature[Tool]Alternative AAlternative B
Speed50ms200ms150ms
Memory10MB50MB30MB
Feature XYesNoPartial
Feature YYesYesNo
Choose [Tool] when: [specific use case] Choose Alternative A when: [specific use case]
undefined
功能[工具]竞品A竞品B
速度50ms200ms150ms
内存占用10MB50MB30MB
功能X支持不支持部分支持
功能Y支持支持不支持
选择[工具]的场景： [具体适用场景] 选择竞品A的场景： [具体适用场景]
undefined

Installation (Multiple Methods)

多方式安装模板

markdown
undefined
markdown
undefined

Installation

安装

Quick Install (Recommended)

快速安装（推荐）

bash
curl -sSL https://example.com/install.sh | bash
bash
curl -sSL https://example.com/install.sh | bash

Package Managers

包管理器安装

bash
undefined
bash
undefined

macOS

macOS

brew install mytool
brew install mytool

Linux

Linux

apt install mytool # Debian/Ubuntu dnf install mytool # Fedora
apt install mytool # Debian/Ubuntu dnf install mytool # Fedora

Windows

Windows

winget install mytool
undefined
winget install mytool
undefined

From Source

源码编译安装

bash
git clone https://github.com/user/mytool
cd mytool
make install
undefined
bash
git clone https://github.com/user/mytool
cd mytool
make install
undefined

Command Reference

命令参考模板

markdown
undefined
markdown
undefined

Commands

命令说明

Global Flags

全局参数

FlagDescription
-v, --verbose
Increase output verbosity
-q, --quiet
Suppress non-error output
--config PATH
Use custom config file
参数描述
-v, --verbose
提升输出详细程度
-q, --quiet
抑制非错误输出
--config PATH
使用自定义配置文件

mytool init

mytool init

Initialize a new project.
bash
mytool init                    # Interactive setup
mytool init --template minimal # Use template
mytool init --force            # Overwrite existing
初始化新项目。
bash
mytool init                    # 交互式设置
mytool init --template minimal # 使用极简模板
mytool init --force            # 覆盖现有项目

mytool run

mytool run

Execute the main workflow.
bash
mytool run input.txt           # Basic usage
mytool run -o output.json      # Custom output
mytool run --dry-run           # Preview changes
undefined
执行主工作流程。
bash
mytool run input.txt           # 基础用法
mytool run -o output.json      # 指定自定义输出
mytool run --dry-run           # 预览变更
undefined

Troubleshooting

故障排查模板

markdown
undefined
markdown
undefined

Troubleshooting

故障排查

Error: "Permission denied"

错误："Permission denied"（权限不足）

Cause: Installation script lacks execute permissions.
Fix:
bash
chmod +x install.sh
./install.sh
原因： 安装脚本缺少执行权限。
修复方案：
bash
chmod +x install.sh
./install.sh

Error: "Command not found"

错误："Command not found"（命令未找到）

Cause: Binary not in PATH.
Fix:
bash
export PATH="$HOME/.local/bin:$PATH"
原因： 二进制文件未在PATH路径中。
修复方案：
bash
export PATH="$HOME/.local/bin:$PATH"

Add to ~/.bashrc or ~/.zshrc for persistence

如需持久生效，添加到~/.bashrc或~/.zshrc中

undefined
undefined

Error: "Config file not found"

错误："Config file not found"（配置文件未找到）

Cause: Missing configuration.
Fix:
bash
mytool init --config
undefined
原因： 缺少配置文件。
修复方案：
bash
mytool init --config
undefined

Limitations

局限性说明模板

markdown
undefined
markdown
undefined

Limitations

局限性

Current constraints:
LimitationWorkaroundPlanned Fix
Max 10MB filesSplit large filesv2.0
No Windows GUIUse WSLUnder review
Single-threadedUse multiple instancesv1.5
Out of scope:
  • Feature X (use [Alternative] instead)
  • Feature Y (not planned)
undefined
当前限制：
限制临时解决方案计划修复版本
最大支持10MB文件拆分大文件v2.0
无Windows图形界面使用WSL评估中
单线程运行多实例并行v1.5
暂不支持范围：
  • 功能X（建议使用[替代工具]）
  • 功能Y（暂无计划）
undefined

FAQ

常见问题（FAQ）模板

markdown
undefined
markdown
undefined

FAQ

常见问题

<details> <summary><b>Q: How does this compare to [Alternative]?</b></summary>
[Tool] focuses on [specific strength], while [Alternative] excels at [different use case]. Choose [Tool] when you need [criteria].
</details> <details> <summary><b>Q: Can I use this in production?</b></summary>
Yes. [Tool] is used in production by [companies/projects]. See our stability policy.
</details> ```
<details> <summary><b>问：该工具与[竞品]相比如何？</b></summary>
[工具]专注于[特定优势]，而[竞品]擅长[不同场景]。当你需要[特定条件]时选择[工具]。
</details> <details> <summary><b>问：能否在生产环境中使用？</b></summary>
可以。[工具]已被[企业/项目]用于生产环境。详见我们的稳定性政策。
</details> ```

Badge Reference

徽章引用模板

markdown
<!-- CI Status -->
![CI](https://github.com/USER/REPO/actions/workflows/ci.yml/badge.svg)

<!-- Version -->
![Version](https://img.shields.io/github/v/release/USER/REPO)

<!-- License -->
![License](https://img.shields.io/badge/license-MIT-blue)

<!-- Downloads -->
![Downloads](https://img.shields.io/github/downloads/USER/REPO/total)

<!-- Package Managers -->
![npm](https://img.shields.io/npm/v/PACKAGE)
![PyPI](https://img.shields.io/pypi/v/PACKAGE)
![Crates.io](https://img.shields.io/crates/v/PACKAGE)
![Gem](https://img.shields.io/gem/v/PACKAGE)
markdown
<!-- CI状态 -->
![CI](https://github.com/USER/REPO/actions/workflows/ci.yml/badge.svg)

<!-- 版本号 -->
![Version](https://img.shields.io/github/v/release/USER/REPO)

<!-- 许可证 -->
![License](https://img.shields.io/badge/license-MIT-blue)

<!-- 下载量 -->
![Downloads](https://img.shields.io/github/downloads/USER/REPO/total)

<!-- 包管理器版本 -->
![npm](https://img.shields.io/npm/v/PACKAGE)
![PyPI](https://img.shields.io/pypi/v/PACKAGE)
![Crates.io](https://img.shields.io/crates/v/PACKAGE)
![Gem](https://img.shields.io/gem/v/PACKAGE)

Progressive Disclosure

渐进式展示

For long READMEs (1000+ lines):
markdown
<details>
<summary><b>Advanced Configuration</b></summary>

[Detailed content here]

</details>
Or externalize:
  • docs/CONFIGURATION.md
  • docs/ARCHITECTURE.md
  • docs/CONTRIBUTING.md
Keep README focused on the 80% use case.
对于超过1000行的长README：
markdown
<details>
<summary><b>高级配置</b></summary>

[详细内容]

</details>
或拆分至外部文档：
  • docs/CONFIGURATION.md
  • docs/ARCHITECTURE.md
  • docs/CONTRIBUTING.md
保持README聚焦于80%用户的核心需求。

Pre-Publication Checklist

发布前检查清单

Hero:
  • Logo/image present
  • Badges current and working
  • One-liner describes the problem solved
  • Quick install command visible
Content:
  • TL;DR within first scroll
  • Every feature has an example
  • Code blocks are copy-paste ready
  • 3+ installation methods documented
Trust:
  • Comparison with alternatives (honest)
  • Limitations documented
  • Top 5 errors in troubleshooting
  • All links verified
Polish:
  • Consistent terminology
  • No stale badges
  • Grammar/spelling checked
标题区：
  • 包含Logo/图片
  • 徽章为最新且可正常显示
  • 一句话描述清晰说明解决的问题
  • 快速安装命令可见
内容：
  • TL;DR在首屏范围内
  • 每个功能都配有示例
  • 代码块可直接复制使用
  • 记录了3种及以上安装方式
可信度：
  • 与竞品的对比真实客观
  • 已记录局限性
  • 故障排查包含Top5常见错误
  • 所有链接均已验证
细节优化：
  • 术语表述一致
  • 无失效徽章
  • 语法/拼写检查无误

Anti-Patterns

反模式

Do NOTDo Instead
Start with installationStart with value proposition
"This tool is a...""This tool solves..."
Screenshot-only demosExecutable code blocks
Claim without exampleExample per feature
Hide limitationsDedicated section
Single install methodMultiple pathways
Ignore errorsTroubleshooting section
切勿正确做法
开篇就讲安装步骤先展示价值主张
“该工具是一款...”“该工具解决了...”
仅用截图演示提供可执行的代码块
空口无凭的宣称每个功能配示例
隐藏局限性设置专门板块说明
仅提供一种安装方式提供多种途径
忽略错误场景增设故障排查板块

Reference Examples

参考示例

Study these for excellent README patterns:
  • ripgrep - Benchmark data, comparison matrices
  • bat - Feature highlights, visual demos
  • starship - Configuration presets, install matrix
  • jq - Tutorial progression, manual linking
以下项目的README是优秀范式，可参考学习：
  • ripgrep - 基准数据、对比矩阵
  • bat - 功能亮点、可视化演示
  • starship - 配置预设、安装矩阵
  • jq - 教程进阶、手册链接