假设您创建了一个程序或启动了一个开源项目，现在您吸引了人们的注意。他们开始提出越来越多的问题，占用您越来越多的宝贵开发者时间来解答。他们塞满您的邮箱，有时甚至在您的 IRC 频道中发送垃圾信息，而且经常重复相同的问题。您知道您需要提供一些书面材料来帮助您的用户。但是您应该从哪里开始？您可以使用哪些工具？您选择哪种输出格式？您必须涵盖哪些主题？
通常，人们会在这个时候退缩，并没有真正开始写作。毕竟，您是开发者，而不是技术文档撰写者，对吗？虽然这可能是事实，但我们不要忘记，文档是项目的重要组成部分。
开始写作
我假设您是从头开始，所以启动您最喜欢的编辑器，写下您的第一行文档。将第一个文件命名为 README。使用纯文本作为文件格式，因为它易于版本控制。
使用诸如 Markdown 或 reStructuredText 之类的标记语言，
您可以轻松地将文本转换为所需的输出格式，例如 PDF 或 HTML，例如使用 pandoc。作为额外的好处，大多数代码托管平台都会解析 README 文件并正确呈现大多数标记语言。
快速入门模板
为了概述文档，您可以使用下面的 markdown 格式模板。从版本标识符或日期开始。使用 ISO 日期格式或写出月份的名称，以便其他国家/地区的人们不会混淆月份和日期。
README v0.0 / 2015 年 6 月 1 日
# 项目名称
## 简介
用一到两段话（最多）向您的用户概述您项目的目的和功能。因为有时一张图片胜过千言万语，所以在适当的时候包含屏幕截图。
## 用法
提供简短的代码片段（如果适用），或简短的用法说明
## 贡献
给出关于如何参与您的项目补丁的说明。
## 帮助
解释哪些沟通渠道可用于请求帮助。经过验证的沟通渠道包括邮件列表、IRC 频道和论坛。还要确保告诉您更有经验的用户如何以及在哪里提交错误或功能请求，可能将他们转变为项目参与者。
## 安装
### 要求
列出您的项目要按预期工作所需的任何内容。
### 安装
描述如何安装您的程序。要精确并给出示例。不要假设您的用户知道如何从我的 github 仓库克隆。请记住，您的一些用户可能完全不熟悉系统管理或软件开发。
### 配置
安装软件后，用户可能需要对其进行配置。列出配置选项并解释如何以及在哪里设置它们。
## 鸣谢
有时也称为作者，这是项目贡献者的列表。
## 联系方式
人们可能出于各种原因想要与您联系，从 DCMA 删除通知到关于如何向您的项目捐款的问题。提供联系信息，例如电子邮件地址，并记住，一些国家/地区可能依法要求某些信息，例如完整的邮政地址、网站 URL 和公司名称。
## 许可证
本项目根据 [插入许可证] 获得许可。许可证应放在一个单独的名为 LICENSE 的文件中，因此不要在您的文档中详细解释它。另外，不要忘记指定您使用的第三方库和程序的许可证。
有时在文档开头包含目录 (TOC) 是有意义的，特别是当您的 README 文件超过几个段落时。如果您认为 README 文件变得太大，请将一些更详细的部分（例如安装或配置部分）放入它们自己的文件中。
结论
编写您的第一个文档似乎不像您最初想象的那么困难或耗时，不是吗？现在您有了一个可以构建的起点。不要忘记更新您的 README，以使其与您项目的开发和新版本保持同步。
话题
本文是 Rikki Endsley 协调的 Doc Dish 专栏 的一部分。要为本专栏投稿，请提交您的故事想法或通过 open@opensource.com 联系我们。
2 条评论