项目文档模板_用于启动项目文档的模板

项目文档模板

假设您已经创建了一个程序或启动了一个开源项目，现在您已经引起了人们的关注。 他们开始提出越来越多的问题，越来越多的宝贵开发人员需要时间来回答。 它们会填满您的邮箱，有时甚至会向您的IRC频道发送垃圾邮件，并经常重复相同的问题。 您知道需要以书面形式提供一些帮助用户的信息。 但是你应该从哪里开始呢？ 您可以使用哪些工具？ 您选择哪种输出格式？ 您必须涵盖哪些主题？

通常这是人们退出并实际上不开始写作的地方。 毕竟，您是开发人员，而不是技术作家，对吗？ 尽管这可能是正确的，但请不要忘记文档是项目的重要组成部分。

动笔

我认为您是从头开始的，因此启动您喜欢的编辑器并编写第一行文档。 将该第一个文件称为README。 使用纯文本作为文件格式，因为它可以轻松地进行版本控制。

使用Markdown或reStructuredText等标记语言，
例如，使用pandoc可以轻松地将文本转换为所需的输出格式，例如PDF或HTML。 另外，大多数代码托管平台都可以解析README文件并正确渲染大多数标记语言。

快速入门模板

要概述文档，您可以使用下面的降价格式的模板。 以版本标识符或日期开头。 使用ISO日期格式或写出月份的名称，以便其他国家/地区的人不会混淆月份和月份。

README v0.0 / 2015年6月1日

＃ 项目名称

＃＃ 介绍

一两个段落（最多）为您的用户提供项目目的和功能的概述。 由于有时一张图片值一千个字，因此请在适当时附上屏幕截图。

##用法

提供简短的代码段（如果适用）或简短的使用说明

##贡献

提供有关如何参与项目修补程序的说明。

＃＃ 救命

说明可以使用哪些沟通渠道来请求帮助。 具有良好记录的通讯渠道是邮件列表，IRC渠道和论坛。 另外，请务必告诉您经验丰富的用户如何以及在何处提交错误或功能请求，有可能使他们成为项目参与者。

##安装

＃＃＃ 要求

列出您的项目所需的任何东西，以使其按预期工作。

###安装

描述如何安装程序。 准确并举一些例子。 不要以为您的用户知道如何从我的github存储库克隆 。 请记住，您的某些用户可能对系统管理或软件开发完全不熟练。

###配置

安装软件后，用户可能需要对其进行配置。 列出配置选项，并说明如何以及在何处进行设置。

##积分

有时也称为Authors ，这是项目贡献者的列表。

＃＃ 联系

人们可能出于各种原因希望与您联系，从DCMA撤下通知到有关如何向您的项目捐款的问题，不一而足。 提供联系信息，例如电子邮件地址，并请记住，某些国家/地区可能会依法要求某些信息，例如完整的邮政地址，网站URL和公司名称。

＃＃ 执照

该项目已获得[插入许可证]的许可。 许可证应该在一个单独的文件LICENSE中，因此不要在文档中对其进行详细说明。 另外，不要忘记指定您使用的第三方库和程序的许可证。

有时在文档的开头包含目录（TOC）是有意义的，尤其是当您的README文件包含多个段落时。 如果您认为README文件太大，则将一些更详细的部分（例如安装或配置部分）放入其自己的文件中。

结论

编写您的第一个文档似乎并不像您最初想的那样费力或费时，是吗？ 现在，您可以建立一个起点。 不要忘记更新自述文件，以使其与项目的开发和新发行版保持一致。

文件
碟

本文是Rikki Endsley协调的Doc Dish专栏的一部分。 要撰写本专栏文章，请提交您的故事创意或通过open@opensource.com与我们联系。

翻译自: https://opensource.com/business/15/6/template-starting-project-documentation

项目文档模板