文档编写软件_编写第一个软件文档的指南

文档编写软件

As a developer, your pride and joy is your code. It’s readable, it meets DRY principles, it reflects best practices, and the end product is a great tool that solves some kind of problem for its target users. However, no matter how much work you’ve put into your code, if your software comes with no documentation, or you write documentation as an afterthought and treat it with little importance, it’s likely users will find little joy in working with it, and eventually opt for a different, more user-friendly product.

作为开发人员，您的骄傲和喜悦就是您的代码。 它可读性强，符合DRY原则，反映了最佳实践，并且最终产品是解决其目标用户某种问题的出色工具。 但是，无论您在代码中投入了多少工作，如果您的软件没有提供文档，或者您只是事后考虑编写文档，而对文档的重视程度都不高，则用户使用该文档可能会感到无比愉悦，并且最终选择了另一种更人性化的产品。

In this article, you’ll find a number of practical guiding principles to get you up and running with writing your first software documentation.

在本文中，您将找到许多实用的指导原则，以帮助您起步并编写第一个软件文档。

为什么文件很重要 (Why Documentation Is Important)

In reference to your software, Mike Pope has a fitting saying that goes like this: If it isn’t documented, it doesn’t exist.

对于您的软件， Mike Pope的说法很恰当： 如果没有记录，则说明该文件不存在 。

Why’s that? Well, just to take my personal experience as an example, I was browsing the Web looking for new JavaScript animation libraries to try out and I came across one with a description of its features that I really liked. However, there was no documentation, not even a Getting Started section, but just a bare-bones API page with almost no explanations or examples. Do you think I ended up using that library? Of course, I didn’t. I got so frustrated with it that I moved on to something that made more sense to me.

为什么？ 嗯，以我的个人经验为例，我正在浏览Web以寻找新JavaScript动画库进行尝试，然后偶然发现了一个我非常喜欢的功能描述。 但是，没有文档，甚至没有“入门”部分，只有一个基本的API页面，几乎没有解释或示例。 您是否认为我最终使用了该库？ 当然，我没有。 我对此感到非常沮丧，以至于继续研究对我来说更有意义的东西。

To the question of why good JavaScript libraries fail, Nicholos Zakas gives the following answer:

对于为什么好JavaScript库失败的问题 ， Nicholos Zakas给出了以下答案 ：

Lack of documentation. No matter how wonderful your library is and how intelligent its design, if you’re the only one who understands it, it doesn’t do any good. Documentation means not just autogenerated API references, but also annotated examples and in-depth tutorials. You need all three to make sure your library can be easily adopted.

缺乏文件资料 。 不管您的图书馆有多精彩，其设计多么聪明，如果您是唯一一个了解图书馆的人，那么它就没有任何用处。 文档不仅意味着自动生成的API引用，还意味着带注释的示例和深入的教程。 您需要全部三个，以确保可以轻松采用您的库。

Another important reason why your software docs are crucially important is that they serve as a communication tool between your present self and your future self, and also between your present self and other developers who eventually might find themselves working on your software. Even if you write readable and commented code, this doesn’t necessarily mean it will still be clear to you in six months’ time why you wrote a function, or any other piece of your code for that matter, the way you did.

您的软件文档之所以至关重要的另一个重要原因是，它们充当了您现在的自我和未来的自我之间以及您现在的自我与最终可能发现自己正在使用软件的其他开发人员之间的沟通工具。 即使您编写可读和注释的代码，这也不一定意味着您六个月后仍会清楚地知道为什么要编写函数或编写代码的其他方式。

Documentation allows you to transfer the why behind code. Much in the same way code comments explain the why, and not the how, documentation serves the same purpose. — A Beginner’s Guide to Writing Documentation

文档使您可以传输原因代码。 代码注释在很大程度上以相同的方式解释了为什么文档而不是如何文档具有相同的目的。 — 编写文档的初学者指南

Surely, you want people to use your code and also to be able eventually to update it and improve on it. These are all contributing factors to the growth of a supporting community behind your product, which is important for it to gain robustness, maturity, and success.

当然，您希望人们使用您的代码，并最终能够对其进行更新和改进。 这些都是促成产品背后支持社区发展的因素，这对于获得强大，成熟和成功的产品至关重要。

It’ll be mighty hard to accomplish all this if your software doesn’t have great docs to go with it.

如果您的软件没有出色的文档，很难完成所有这些工作。

适用于谁的软件文档 (Who Software Documentation Is For)

When writing anything, make sure it’s clear in your mind who your audience is. Docs are no exception to this rule. Doing so clarifies in your head the problems your audience is likely to face, the familiarity it’s likely to have with your product or the prerequisites for using your product. This information is crucial to the way you create the content and the language you use.

在编写任何内容时，请确保您清楚自己的听众是谁。 文档也不例外。 这样做可以在您的头脑中弄清楚听众可能会遇到的问题，对产品的熟悉程度或使用产品的先决条件。 这些信息对于您创建内容的方式和使用的语言至关重要。

There are two kinds of documentation this article is not concerned with:

本文不涉及两种文档：

1. User manuals. For instance, my sister might decide to use WordPress for publishing her own blog. She’s not a developer, but she’s heard that non-devs can get their blog up and running in no time with WordPress. Now she’ll be needing instructions on how to download and configure the software on her server, how to write, publish, and update her posts, how to add images to a post, etc. In other words, she’ll need a user manual.
   用户手册。 例如，我姐姐可能决定使用WordPress发布自己的博客。 她不是开发人员，但听说非开发人员可以立即使用WordPress建立并运行他们的博客。 现在，她将需要有关如何在服务器上下载和配置软件，如何编写，发布和更新其帖子，如何向帖子中添加图像等的说明。换句话说，她将需要一个用户手册。
2. Project documentation. This kind of documentation has more to do with the project than with the software itself, although some of its content could go in a project’s Readme file. To continue with the WordPress example, after getting lots of practice with WordPress, I might decide I’d like to add a feature to the software or fix a bug or two. In this case I’ll need to know things like changelogs, conventions and best practices, contribution policies, how to participate in team discussions relevant to the task at hand, etc.
   项目文档。 这种文档更多地与项目有关，而与软件本身无关，尽管其某些内容可以放在项目的自述文件中。 为了继续使用WordPress示例，在对WordPress进行了大量实践之后，我可能会决定要向该软件添加功能或修复一两个bug。 在这种情况下，我将需要了解诸如变更日志，约定和最佳实践，贡献政策，如何参与与手头任务相关的团队讨论之类的事情。

The kind of documentation I’ve got in mind here is mainly aimed at developers who have different levels of familiarity with your software and need to use it in their projects. For instance, if I’m creating a WordPress theme, then I’ll need to know how to get started, how to include style sheets and JavaScript documents, how to communicate with the database to display posts, etc.

我在这里想到的这类文档主要针对那些对您的软件有不同程度的了解并需要在其项目中使用它的开发人员。 例如，如果我正在创建WordPress主题，则需要了解如何入门，如何包括样式表和JavaScript文档，如何与数据库进行通信以显示帖子等。

文件中包含什么 (What to Include in Your Documentation)

A popular approach is Readme Driven Development, championed by Tom Preston-Werner. It consists of writing the Readme document before you even start writing any code. This document is an introduction to your software and usually includes:

一种流行的方法是Tom Preston-Werner倡导的自述驱动开发 。 它包括在开始编写任何代码之前就编写自述文件。 本文档是您的软件的简介，通常包括：

• an explanation of what your software does and what problem it solves
  您的软件做什么以及解决什么问题的说明
• an example illustrating the circumstances in which your code would normally be used
  一个示例，说明在什么情况下通常会使用您的代码
• links to the code and bugs tracker
  链接到代码和错误跟踪器
• FAQs and ways to ask for support
  常见问题解答和寻求支持的方法
• instructions on how to install your software
  有关如何安装软件的说明
• license information
  许可证信息

However, in my view, having a solid documentation that can really help developers who use your software/library should go well beyond the classical Readme file. Following Daniele Procida, I suggest you include the following items in your documentation material for a great user experience.

但是，我认为拥有可靠的文档可以真正帮助使用您的软件/库的开发人员超越传统的自述文件。 在Daniele Procida之后 ，建议您在文档材料中包括以下内容，以提供出色的用户体验。

讲解 (Tutorials)

A beginner will love to find a tutorial in your software docs. Tutorials are about showing users how to complete a project using your software, so that they can quickly get a sense of what they can do with it.

初学者会喜欢在您的软件文档中找到一个教程。 教程旨在向用户展示如何使用您的软件来完成项目，以便他们可以快速了解如何使用该项目。

Tutorials are lessons that take the reader by the hand through a series of steps to complete a project of some kind. They are what your project needs in order to show a beginner that they can achieve something with it. — Daniele Procida

教程是使您亲身经历一系列步骤以完成某种项目的课程 。 它们是您的项目所需要的，以便向初学者展示他们可以用它来实现目标。 — 丹妮尔·普罗奇达

入门指南 (How-to Guides)

How-to guides help users solve a real-world task using your software. Procida compares them to recipes in the sense that they are directions you give users so that they can successfully reach a certain goal. Unlike tutorials, which are aimed at complete beginners, how-to guides assume users already possess some basic knowledge of features, tools, and of how to perform simple tasks.

操作指南可帮助用户使用您的软件解决实际任务。 Procida将它们与食谱进行比较，因为它们是您为用户提供的指导，以便他们可以成功达到特定目标。 与针对完全初学者的教程不同，操作指南假定用户已经具备一些有关功能，工具以及如何执行简单任务的基本知识。

参考指南 (Reference Guides)

Reference guides are technical references of your software’s code — functions, APIs, etc. — and offer a basic description of how to use the software. For example, you’ll find an illustration of how to instantiate a specific class, how to call a particular method, and so on.

参考指南是软件代码(功能，API等)的技术参考，并提供有关如何使用软件的基本描述。 例如，您将找到有关如何实例化特定类，如何调用特定方法等的说明。

Reference guides are technical descriptions of the machinery and how to operate it. — Daniele Procida

参考指南是有关机器及其操作方法的技术说明 。 — 丹妮尔·普罗奇达

This is the piece of documentation you’re likely to find in most projects. Developers tend to be quite good at writing it since they know all about their code and how to use it.

这是您在大多数项目中可能会找到的文档。 开发人员往往很擅长编写代码，因为他们了解所有代码以及如何使用它。

说明 (Explanation)

Explanations are a deep dive into, or a discussion on, a particular topic you think is relevant to a higher-level understanding of your software. About explanations, Procida points out that —

解释是对您认为与更高层次的软件理解有关的特定主题的深入研究或讨论。 关于解释，Procida指出-

This section of documentation is rarely explicitly created, and instead, snippets of explanation are scattered among other sections. Sometimes, the section exists, but has a name such as Background or Other notes and doesn’t really do justice to the function.

本文档的这一部分很少明确创建，相反，解释性摘要分散在其他部分中。 有时，该节存在，但具有诸如Background或Other注释之类的名称，并不能真正使该功能合理化。

A topic isn’t defined by a specific task you want to achieve, like a how-to guide, or what you want the user to learn, like a tutorial. It’s not defined by a piece of the machinery, like reference material. It’s defined by what you think is a reasonable area to try to cover at one time, so the division of topics for discussion can sometimes be a little arbitrary.

主题不是由您想要实现的特定任务定义的，例如操作指南，也不是您希望用户学习的内容(例如教程)。 它不是由某种机械定义的，例如参考资料。 它是由您认为一次可以尝试覆盖的合理区域定义的，因此讨论的主题划分有时可能会有些随意。

您需要注意的事情 (Things You Need to Pay Attention To)

Let’s go through some useful pointers about making your docs user-friendly and relevant.

让我们通过一些有用的指示来使您的文档变得用户友好和相关。

使您的文档可发现 (Make Your Docs Discoverable)

It’s a good idea to put some work into making your software documentation easy to find. You could use some SEO techniques together with some marketing strategies so that as many users as possible can get hold of it.

进行一些工作以使软件文档易于查找是个好主意。 您可以将一些SEO技术与一些营销策略结合使用，以便尽可能多的用户能够掌握它。

Also, what you put in your docs should be organized into a structure that makes searching for specific information a breeze. Steve Konves recommends you structure your docs in a singly linked tree: starting from the root node, which should be placed in an obvious location for every interested user to discover, all other items can be easily accessed. The project’s Readme file lends itself to working really well as a great root node for the entire tree.

另外，您在文档中输入的内容应组织成一个结构，使搜索特定信息变得轻而易举。 Steve Konves建议您将文档构建在一个单链接的树中：从根节点开始，该节点应放置在明显的位置，以便每个感兴趣的用户都可以发现，所有其他项目都可以轻松访问。 该项目的自述文件使其可以很好地用作整个树的根节点。

Also, if you receive help requests from your software’s users, you could write the answers and make them available in an easily accessible FAQs page. Doing so will decrease the time you spend helping users, but it will also give you a clearer idea of the kind of information users need most frequently so that you can document them first and keep them in a prominent place in your docs.

另外，如果您收到软件用户的帮助请求，则可以编写答案并在易于访问的“常见问题”页面中将其提供。 这样做可以减少您花费在帮助用户上的时间，但同时也可以使您更清晰地了解用户最需要的信息类型，以便您可以首先对其进行记录，并将其放在文档中的重要位置。

确保您的文档是最新的并且没有错误 (Ensure Your Docs Are Up-to-date and Free of Bugs)

Easily accessing your software documentation is great, but if users find out that its content is out of date or the sample code or instructions lead to buggy results, this gets frustrating, to say the least. Still, Steve Konves suggests you keep your docs close to the code — for instance, in source control. This way, when developers update the code, they’ll notice the documentation material, which makes updating the docs a much more likely occurrence.

轻松访问您的软件文档非常有用，但是，如果用户发现其内容已过期，或者示例代码或说明导致错误的结果，至少可以这样感到沮丧。 不过，史蒂夫·康维斯(Steve Konves)还是建议您将文档保持在代码附近(例如，在源代码管理中)。 这样，当开发人员更新代码时，他们会注意到文档资料，这使得文档更新的可能性更大。

Also, to minimize the occurrence of bugs, thoroughly test the instructions and the code samples you provide in your docs.

另外，为了最大程度地减少错误的发生，请彻底测试您在文档中提供的说明和代码示例。

额外提示和一些热门示例 (Extra Tip and Some Popular Examples)

Don’t stop at documentation. Blog posts are great for making your software and its features known to a wide audience of potential users. Use your blog to offer clarifications of what your product does, deliver user-friendly tutorials, tips and tricks, walk-throughs, explain updates, etc. You can include your blog in a stand-alone website dedicated to your software — perhaps with a forum — around which a strong community can gather and grow.

不要停留在文档上。 博客文章非常适合使潜在用户了解您的软件及其功能。 使用您的博客提供产品功能的说明，提供用户友好的教程，技巧和窍门，演练，解释更新等。您可以将博客包含在专门针对软件的独立网站中-可能包含论坛-一个强大的社区可以聚集并成长的论坛。

A great example of this wider idea of documentation in my view is implemented by GreenSock, a widely successful JS animation platform, which I find myself using a lot, not least because its website makes available easy-to-use and well-structured docs, a super helpful forum, blog posts, quick tips, and much more.

在我看来，这种广泛的文档构想的一个很好的例子是由GreenSock实现的， GreenSock是一个广受欢迎的JS动画平台，我发现自己经常使用它，不仅因为它的网站提供了易于使用且结构合理的文档，超级有用的论坛，博客文章，快速提示等。

React and Vue.js can also be counted as great examples. As soon as you access their respective websites, the home page tells you what each library is good for in a quick tagline, and then goes into more details on why the library can be considered a great choice for your project. Both websites make getting started less intimidating using gentle introductions, illustrative snippets, short tasks beginners can accomplish using code playgrounds, etc. Once users have gained a bit of confidence with the new software, they can find the more technical API docs readily, plus pages detailing how to get help, displaying information on the ecosystem, offering a news or blog section, etc.

React和Vue.js也可以算作很好的例子。 一旦访问它们各自的网站，主页就会在快速标语中告诉您每个库的优点，然后详细介绍为什么将库视为您的项目的最佳选择。 这两个网站都通过使用简短的介绍，说明性摘录，初学者可以使用代码游乐场来完成的简短任务等，减少了上手的恐惧。一旦用户对新软件有了一点信心，他们就可以轻松找到更多技术性的API文档以及页面。详细说明如何获得帮助，在生态系统上显示信息，提供新闻或博客部分等。

To leave the JS zone and go into the field of popular UI libraries with great websites, I can’t leave out Bootstrap. On the Bootstrap website you’ll find right away what the library is good for and how to get started quickly, as well as comprehensive and well-structured docs and a blog to keep users updated on what’s new.

要离开JS专区并进入拥有大量网站的流行UI库领域，我不能忘记Bootstrap 。 在Bootstrap网站上，您会立即找到该库的优点以及如何快速入门，以及全面，结构合理的文档和博客，以使用户随时了解最新信息。

结论 (Conclusion)

Writing good documentation has its challenges, but it certainly pays off a hundred times if you think how much easier it will be for your users to implement your software’s capabilities. This in turn contributes to your software’s popularity, which makes it attractive and therefore open to the possibility of giving rise to a community of developers who are willing to invest their time in learning it deeply and contributing to its growth, stability, and long-term usage.

编写好的文档有其挑战，但是如果您认为用户实现软件功能将变得多么容易，它肯定会获得一百倍的回报。 反过来，这也有助于提高软件的受欢迎程度，从而使其具有吸引力，因此有可能吸引一群开发人员，他们愿意投入时间来深入学习它，并为软件的增长，稳定性和长期发展做出贡献。用法。

翻译自: https://www.sitepoint.com/writing-software-documentation/

文档编写软件