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

Есть ли рекомендации по написанию справочных страниц?

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

Есть и другие, такие как OPTIONS, AUTHOR.

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


linux unix manpage
person jac_no_k    schedule 23.04.2009    source источник

Ответы (5)


arrow_upward
4
arrow_downward

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

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

person Brandon Rhodes    schedule 23.04.2009

arrow_upward
1
arrow_downward

Раздел ОШИБКИ хорош, а раздел ПРИМЕРЫ всегда полезен. Некоторые справочные страницы содержат раздел ФАЙЛЫ, в котором перечислены соответствующие файлы конфигурации, или раздел ОКРУЖАЮЩАЯ СРЕДА, подробно описывающий любые важные переменные среды.

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

person vezult    schedule 23.04.2009
comment
ОШИБКИ действительно нужны только в том случае, если есть известные ошибки. - person X-Istence; 23.04.2009
comment
Истинный. Мне действительно нужно было предоставить логику if/then? - person vezult; 23.04.2009
comment
ПРИМЕРЫ необходимы для программ с множеством различных операций, и страница руководства должна их отражать. ПРИМЕРЫ часто являются полезным способом сделать это (см., например, руководство mplayer). - person hlovdal; 01.12.2010

arrow_upward
1
arrow_downward

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

person Charlie Martin    schedule 23.04.2009

arrow_upward
1
arrow_downward

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

Одна вещь, которую я часто делаю со страницами руководства, — это попытка найти связанную команду, хотя я знаю, что вещь, на которую я смотрю, не делает то, что я хочу. В этом случае SEE ALSO великолепен.

person Community    schedule 26.10.2009

arrow_upward
0
arrow_downward

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

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

person X-Istence    schedule 23.04.2009