readme-writer
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseThe general flow of a README:
- A section describing what the package does and why it's important (i.e. "what's in it for me" for the user)
- A section on how to install and use the package
- A section on common configuration options and methods
- A section on how to contribute or pointer to CONTRIBUTING.md, notes on the developer's build environment and potential portability problems.
- a brief explanation of any unusual top-level directories or files, or other hints for readers to find their way around the source;
README的通用结构：
- 一个说明包功能及其重要性的章节（即用户视角的“对我有什么用”）
- 关于如何安装和使用该包的章节
- 常见配置选项和方法的章节
- 关于如何贡献的章节或指向CONTRIBUTING.md的链接，以及开发者构建环境说明和潜在的可移植性问题提示
- 对任何不常见的顶级目录或文件的简要说明，或其他帮助读者理解源码结构的提示
Github-flavored markdown
Github-flavored markdown
Since most all of my projects are Github, you have have some neat markdown block extensions available:
[!CAUTION] [!IMPORTANT] [!NOTE] [!TIP] [!WARNING]
Use these to call out any semantic sections.
由于我的大多数项目都托管在Github上，你可以使用一些实用的Markdown块扩展：
[!CAUTION] [!IMPORTANT] [!NOTE] [!TIP] [!WARNING]
使用这些来标记特殊语义的章节。
Reading level
阅读难度
I prefer a Fleisch-Kincaid reading level of 9th grade or below. Revise the README until it is below a 9th grade level. Use .
scripts/flesch_kincaid.rb我偏好弗莱施-金凯德（Fleisch-Kincaid）阅读难度等级在9年级及以下。请反复修订README直到达到该难度要求。可使用工具检测。
scripts/flesch_kincaid.rbESL audience
ESL受众
Many of the people reading a software project README are not native speakers of English.
scripts/top1000.txtDO use active voice where possible.
DON'T assume passive constructions are easy just because the words are simple.
DO keep noun phrases short and direct.
DON'T stack multiple modifiers before nouns ("the recently revised standardized testing protocol").
DO limit embedded clauses—one level of nesting is usually manageable.
DON'T assume simple vocabulary guarantees comprehension; "The man who the dog that bit the cat chased ran away" uses basic words but is notoriously hard to parse.
DO use conditionals sparingly, favoring simple "if/then" structures.
DON'T rely heavily on mixed or inverted conditionals ("Had she known...").
DO make logical connections explicit with transition words (however, therefore, because).
DON'T expect readers to infer relationships between ideas.
DO spread information across multiple sentences when needed.
DON'T pack too many new concepts into a single sentence.
DO explain or gloss cultural references.
DON'T assume shared background knowledge about idioms, historical events, or cultural touchstones.
许多阅读软件项目README的读者并非英语母语者。
scripts/top1000.txt尽可能使用主动语态。
不要因为词汇简单就认为被动语态容易理解。
保持名词短语简短直接。
不要在名词前堆砌多个修饰语（例如“最近修订的标准化测试协议”）。
限制嵌套从句——通常一层嵌套是可接受的。
不要认为简单词汇就一定能保证理解；“被那只咬了猫的狗追赶的男人跑掉了”这句话用的都是基础词汇，但解析起来非常困难。
尽量少用条件句，优先使用简单的“如果/那么”结构。
不要过度使用混合或倒装条件句（例如“要是她早知道……”）。
使用过渡词（然而、因此、因为等）明确逻辑关联。
不要指望读者自行推断观点之间的关系。
必要时将信息拆分到多个句子中。
不要在单个句子中塞入太多新概念。
解释或注释文化相关的引用。
不要假设读者对习语、历史事件或文化符号有共同的背景知识。
Bibliography
参考文献
— GNU Coding Standards, https://www.gnu.org/prep/standards/html_node/Releases.html#i... (July 1, 2021)
— Software Release Practice HOWTO, https://tldp.org/HOWTO/Software-Release-Practice-HOWTO/distp... (Revision 4.1)