放入手册页的最佳做法页面

Question

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

什么应该包含在布局中？标准的有：
NAME
概要
说明
例
另请参阅

还有其他类似选项，作者。

作为一个用户什么是有用的？什么没有帮助？

Answer 1

如果你找不到20世纪70年代贝尔实验室的“troff”文档的任何旧版本的副本，其中有一些关于编写手册页的很好的部分:-)那么我建议在他的网站上试用Jens的"HOWTO" on writing man pages。

---

的Unix 7th Edition手册可在网上​​以多种格式。

Answer 2

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

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

Answer 3

BUGS部分很不错，而EXAMPLES部分总是有用的。某些手册页包含一个 FILES部分，其中列出了相关的配置文件，或者包含ENVIRONMENT部分，详述了任何有影响的环境变量。

要清楚，哪些部分或信息类型对用户有用取决于您正在记录的程序或实用程序的性质。

Answer 4

有一个与UNIX系统分布的规范手册页大纲，或者至少通常有。一般来说，我会放入所有字段，并且如果不适用，则包含一个类似“无”的行。

Answer 5

有时候人们忘记放在手册页中的一件事是函数返回值的含义。这很容易被遗忘，但这种遗漏会让那些必须使用你的功能的人变得更加困难。此外，概要中的简单代码段或者一个很好的最小工作示例非常有用。

我经常用手册页做的一件事是尝试找到一个相关的命令，即使我知道我正在看的东西没有做我想要的。在这种情况下，SEE ALSO很棒。