マニュアルページに入れるベストプラクティス

Question

マニュアルページを作成するためのベストプラクティスガイドラインはありますか？

レイアウトには何を含める必要がありますか？標準的なものです：
NAME
SYNOPSIS
説明
例
は

関連項目OPTIONS、AUTHORのような他のものがあります。

ユーザーとしては何が有益でしょうか？役に立たないものは何ですか？

Answer 1

、:-)私はイェンスさん"HOWTO" on writing man pages上の彼のサイトで試してお勧めしたいです。

---

Unix 7th Editionのマニュアルは、さまざまな形式でオンラインで入手できます。

Answer 2

これはソフトウェアの機能によって異なります。小さなスタンドアロンアプリケーションの場合は、AUTHORセクションをmanページに入れて、ユーザーがバグを見つけた場合にバグを報告する電子メールアドレスを簡単に見つけることができるようにします。

ベストプラクティスに関しては、マニュアルページは簡潔で詳細ではありませんが、必須ではない情報があまり含まれていないことを私が知っているものはありません。例。

Answer 3

バグセクションはいいですし、EXAMPLESセクションは常に役に立ちます。いくつかのマニュアルページには、関連する設定ファイルをリストする FILESセクション、または影響を受ける環境変数を詳述するENVIRONMENTセクションが含まれています。

明確にするために、ユーザーにとって有用なセクションまたはタイプの情報は、文書化しているプログラムまたはユーティリティの性質によって異なります。あなたはmanページを書くことにいくつかの素晴らしいセクションを持っていた1970年代のベル研究所「のtroff」のドキュメントの任意の古いバインドされたコピーを、見つけることができない場合

Answer 4

UNIXシステムで標準的なマニュアルページの概要が配布されているか、少なくとも通常は存在します。一般に、私はすべてのフィールドを入力し、適用されない場合は "none"のような行を追加します。

Answer 5

マニュアルページに入れることを時々忘れることの1つは、関数の戻り値の意味です。忘れるのは簡単ですが、その省略は、あなたの機能を使用しなければならない人にとって、人生をより困難にする可能性があります。また、SYNOPSISのシンプルなコードセグメントや、最小限の作業例が非常に便利です。

私がよくmanページで行うことの1つは、私が見ていることが自分の望むことをしていないことを知っていても、関連するコマンドを見つけようとすることです。この場合、SEE ALSOは素晴らしいです。