Лучшие практики для размещения на странице руководства

Question

Существуют ли рекомендации по написанию man-страниц?

Что должно быть включено в макет? Стандартными являются:
ИМЯ
СИНТАКСИС
ОПИСАНИЕ
Примеры
СМОТРИ ТАКЖЕ

Есть и другие, такие как ОПЦИИ , АВТОР .

Как пользователю, что было бы полезно иметь? Что не помогает?

Answer 1

Если вы не можете найти какие-либо старые переплетенные копии документации «troff» Bell Labs 1970-х годов, в которой есть несколько хороших разделов по написанию man-страниц :-), то я бы предложил попробовать «HOWTO» Дженса по написанию man страницы на его сайте.

---

Руководства Unix 7th Edition доступны в Интернете в различных форматах.

Answer 2

Одна вещь, которую люди иногда забывают поместить в справочные страницы, это значение возвращаемого значения функции. Это легко забыть, но упущение может значительно усложнить жизнь людям, которым приходится использовать вашу функцию. Кроме того, очень полезен простой сегмент кода в SYNOPSIS или хороший минимальный рабочий ПРИМЕР.

Одна вещь, которую я часто делаю со страницами man, - это попытаться найти связанную команду, хотя я знаю, что то, на что я смотрю, не выполняет то, что я хочу. В этом случае СМОТРИ ТАКЖЕ отлично.

Answer 3

Существует каноническая схема справочной страницы, распространяемая с системами UNIX, или, по крайней мере, обычно. В общем, я бы вставил все поля и добавил строку вроде «none», если это не применимо.

Answer 4

Секция BUGS хороша, а секция EXAMPLES всегда полезна. Некоторые справочные страницы содержат Раздел «ФАЙЛЫ», в котором перечислены связанные файлы конфигурации, или раздел «ОКРУЖАЮЩАЯ СРЕДА», в котором указаны все важные переменные среды.

Чтобы было ясно, какие разделы или типы информации полезны для пользователей, зависит от характера программы или утилиты, которые вы документируете.

Answer 5

Это зависит от того, что делает ваше программное обеспечение. Если это небольшое автономное приложение, я бы, конечно, поместил раздел «АВТОР» на странице руководства, чтобы, если пользователи находят ошибки, они могли легко найти адрес электронной почты, чтобы сообщить вам об ошибке.

Что касается лучших практик, ни одной из известных мне, за исключением того, что справочная страница должна быть краткой, подробной, но не содержать слишком много информации, которая не требуется, если это просто инструмент, внутренняя работа не требуется, например .