放入手册页的最佳实践答案

【问题标题】：Best practices to put into a man page放入手册页的最佳实践
【发布时间】：2009-04-23 01:35:51
【问题描述】：

是否有编写手册页的最佳实践指南？

布局中应该包含什么？标准的有：
姓名
概要
说明
示例
参见

还有其他的，例如 OPTIONS、AUTHOR。

作为用户，拥有什么会有用？什么没有帮助？

【问题讨论】：

【解决方案1】：

如果您找不到任何 1970 年代贝尔实验室“troff”文档的旧装订副本，其中有一些关于编写手册页的精彩部分，:-) 那么我建议在 Jens 的网站上尝试一下 Jens 的 "HOWTO" on writing man pages。

Unix 7th Edition 手册以多种格式在线提供。

【讨论】：

【解决方案2】：

BUGS 部分很好，EXAMPLES 部分总是有用的。一些手册页包含一个 FILES 部分列出了相关的配置文件，或者 ENVIRONMENT 部分详细说明了任何有影响的环境变量。

需要明确的是，哪些部分或类型的信息对用户有用取决于您记录的程序或实用程序的性质。

【讨论】：

【解决方案3】：

有一个随 UNIX 系统分发的规范手册页大纲，或者至少通常有。一般情况下，我会填写所有字段，如果不适用，请添加“无”之类的行。

【讨论】：

【解决方案4】：

人们有时会忘记放入手册页的一件事是函数返回值的含义。这很容易忘记，但是对于必须使用您的功能的人来说，遗漏会使生活变得更加困难。此外，SYNOPSIS 中的简单代码段或良好的最小工作示例非常有用。

我经常对手册页做的一件事是尝试找到相关的命令，即使我知道我正在查看的内容并没有达到我想要的效果。在这种情况下，SEE ALSO 很棒。

【讨论】：

【解决方案5】：

这取决于您的软件的功能。如果它是一个小的独立应用程序，我当然会把 AUTHOR 部分放在手册页中，这样如果用户发现错误，他们可以很容易地找到一个电子邮件地址向您报告错误。

至于最佳实践，我不知道，除了手册页应该简洁，详细但不包含太多不需要的信息，如果它只是一个工具，则不需要内部工作例如.

【讨论】：