放入手册页的最佳实践

Question

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

什么应该包括在布局中？ 标准的是：
名称
概要
描述
例子
也可以看看

还有其他像OPTIONS ， AUTHOR 。

作为一个用户有什么用处？ 什么没用？

Answer 1

如果你找不到20世纪70年代贝尔实验室“troff”文档的旧版本，其中有一些关于编写手册页的好文章，那么:-)那么我建议在他的网站上编写人工页面时试用Jens的“HOWTO” 。

---

Unix第7版手册可以在线获得各种格式。

Answer 2

人们有时忘记在手册页中放置的一件事是函数返回值的含义。 这很容易忘记，但遗漏可能会让那些必须使用你功能的人的生活更加艰难。 此外，SYNOPSIS中的简单代码段或良好的最小工作示例非常有用。

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

Answer 3

BUGS部分很不错，EXAMPLES部分总是很有用。 某些手册页包含列出相关配置文件的FILES部分，或包含详细说明任何有影响的环境变量的“环境”部分。

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

Answer 4

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

Answer 5

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

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