放入手册页的最佳实践
是否有编写手册页的最佳实践指南？
布局中应包含哪些内容？ 标准的是：
姓名
概要
描述
示例
另请参阅
还有其他诸如选项、作者。
作为用户，拥有什么会有用？ 什么没有帮助？
Is there a best practices guideline for writing man pages?
What should be included in the layout? The standard ones are:
NAME
SYNOPSIS
DESCRIPTION
EXAMPLES
SEE ALSO
There are others like OPTIONS, AUTHOR.
As a user what would be useful to have? What isn't helpful?
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（5）
如果您找不到 1970 年代贝尔实验室“troff”文档的任何旧装订副本，其中有一些关于编写手册页的不错的部分，:-) 那么我建议尝试 Jens 的 在他的网站上编写手册页的“HOWTO”。
Unix 7th Edition 手册可以以多种格式在线获取。
If you cannot find any old bound copies of 1970s Bell Labs "troff" documentation, which had some nice sections on writing man pages, :-) then I'd suggest trying out Jens's "HOWTO" on writing man pages over at his site.
The Unix 7th Edition manuals are available online in a variety of formats.
BUGS 部分很好，示例部分总是有用的。 一些手册页包含
FILES 部分列出了相关的配置文件，或者 ENVIRONMENT 部分详细说明了任何有影响的环境变量。
需要明确的是，哪些部分或类型的信息对用户有用取决于您正在记录的程序或实用程序的性质。
A BUGS section is nice, and an EXAMPLES section is always useful. Some man pages contain a
FILES section which lists related configuration files, or ENVIRONMENT section detailing any influential environment variables.
To be clear, what sections or type of information are useful to users depends on the nature of the program or utility that you are documenting.
UNIX 系统有一个规范的手册页大纲，或者至少通常有。 一般来说，我会输入所有字段，如果不适用，则包含诸如“none”之类的行。
There is a canonical man page outline distributed with UNIX systems, or at least usually there is. In general, I'd put in all the fields, and include a line like "none" if it doesn't apply.
人们有时忘记在手册页中放入的一件事是函数返回值的含义。 这很容易被忘记，但是遗漏会使必须使用您的功能的人的生活变得更加困难。 此外，概要中的简单代码段或良好的最小工作示例非常有用。
我经常使用手册页做的一件事是尝试找到相关的命令，即使我知道我正在查看的东西并没有达到我想要的效果。 在这种情况下，“SEE ALSO”就非常有用。
One thing which people sometimes forget to put in manual pages is the meaning of the return value of the function. It's easy to forget, but the omission can make life much harder for people who have to use your function. Also, a simple code segment in the SYNOPSIS or a good minimal working EXAMPLE is very useful.
One thing that I often do with man pages is to try to find a related command, even though I know the thing I'm looking at doesn't do what I want. In this case, the SEE ALSO is great.
这取决于您的软件的功能。 如果它是一个小型独立应用程序，我肯定会将作者部分放在手册页中，这样如果用户发现错误，他们可以轻松找到电子邮件地址来向您报告错误。
至于最佳实践，我不知道，除了手册页应该简洁、详细，但不要包含太多不需要的信息，例如，如果它只是一个工具，则不需要内部工作原理。
It depends on what your software does. If it is a small stand-alone application, I would certainly put the AUTHOR section in the man page so that if users find bugs they can easily find an email address to report the bug to you.
As for best practices, none that I know of, other than that the man page should be concise, detailed but not contain too much information that is not required, if it is just a tool the inner workings are not required for example.