将最佳做法放入手册页

是否有写手册页的最佳做法指南？

什么应该包括在布局？ 标准的是：

名称

概要

描述

例子

也可以看看

还有其他的像OPTIONS ， AUTHOR 。作为一个用户有什么用？ 什么没有帮助？如果你找不到20世纪70年代贝尔实验室的“troff”文档的旧版本，那么在编写手册页时会有一些很好的部分:-)那么我会建议在他的网站上编写手册页的时候尝试使用Jens的“HOWTO” 。Unix 7th Edition手册以各种格式在线提供。BUGS部分很好，而EXAMPLES部分总是有用的。 某些手册页包含一个列出相关配置文件的FILES部分，或者包含详述任何有影响力的环境变量的ENVIRONMENT部分。要清楚的是，哪些部分或哪些类型的信息对用户有用取决于您正在记录的程序或实用程序的性质。有一个与UNIX系统分布的规范的手册页大纲，或者至少通常有。 一般来说，我会把所有的字段放在一起，如果不适用的话，会包含“none”这样的一行。有时人们忘记放在手册页中的一件事是函数返回值的含义。 这很容易被遗忘，但遗漏会让那些必须使用你的功能的人变得更加困难。 而且，概要中的一个简单的代码段或一个很好的最小工作示例是非常有用的。我经常用man页面做的一件事就是试图找到一个相关的命令，尽管我知道我正在看的东西并不是我想要的。 在这种情况下，SEE ALSO也很棒。这取决于你的软件的功能。 如果它是一个小型的独立应用程序，我肯定会将AUTHOR部分放在手册页中，这样如果用户发现错误，他们可以很容易地找到一个电子邮件地址来向您报告错误。至于最佳实践，除了手册页应该简洁，详细，但不包含太多不需要的信息外，我不知道的最佳实践，如果它只是一个工具，内部工作不是必需的例如。