web-dev-qa-db-ja.com

開発者からどのレベルのドキュメントが提供されると思いますか?

タイトルはそれをすべて本当に言います。

開発とITがこの種のことをめぐって頭を悩ませていることになる場合があります。 1つ以上のサーバーで実行されているソリューションをインストール、パッチ適用、保守、開始、停止、および診断する場合、どのレベルのドキュメントを期待しますか?

8
cletus

これらすべてを詳細に文書化する必要がありますが、オペレーティングシステム、アプリケーションサーバー、Webサーバーなどの操作が標準である場合、IT運用担当者がその方法を知っていると想定できる場合があります。

Installation:正しく動作しているかどうかを確認する方法など、インストールと構成の方法に関するすべてを文書化します。

アーキテクチャについて、特にさまざまなソリューションコンポーネント間の通信について教えてください(たとえば、ポートの範囲-RPCメカニズムはポートの範囲を使用することがよくあります-範囲が何であり、アプリケーションがいつポートを使い果たす可能性があるかを知る必要があります)。

パッチ適用:アプリケーションに固有のすべてを文書化します-パッチ適用前にシャットダウンする必要があるもの、およびパッチ適用後のフォローアップアクション(キャッシュ、インデックス、クリアまたは再構築が必要な可能性のあるプロキシ)。

Maintenance:正常な動作と異常な動作がどのように見えるかを文書化します-どのキューやその他のものを監視する必要があり、これらの正常な範囲は何ですか。

データの管理方法を教えてください。特に、無制限に大きくなるテーブルやファイル(ログファイルやトランザクション履歴など)を教えてください。これらをどのようにパージする必要があり、古いエントリを削除するとどのような影響がありますか? (報告など)。

標準の「通常どおりのビジネス」/生活管理アクションを実行する方法を教えてください。これには、たとえば、ユーザーアカウントの追加や変更が含まれる場合があります。

必要となる可能性のあるその他の定期的な管理アクションについて教えてください(たとえば、どの証明書が使用され、それらが期限切れになったときに何をするか)。

すべての変更について、それらをロールバックする方法を教えてください(すべての変更が成功するわけではありません)。そして、ロールバック計画をテストしたことを教えてください!

診断:ログファイルの形式と場所、および表示される可能性のあるすべてのアプリケーションエラーメッセージを文書化し、エラーメッセージの意味が間違っていることと、それを修正するために何を変更する必要があるかを示します。 2つの異なるイベントに同じエラーメッセージを使用しないでください。

シャットダウンして起動します:どのように、どのような順序で、特別な手順(サーバーをシャットダウンする前にサーバーに接続をドレインさせるなど)。

これを行う最善の方法は、アプリケーションをフェンスを越えて投げ、IT担当者に必要なものを考えさせることであることに強く反対します。運用ドキュメント(および一般に、アプリケーションの管理機能)は、事前に検討する必要があります。

9

次の質問は次のようになります:開発者が十分なドキュメントを提供しない場合(そうでない場合)はどうなりますか?

開発者が使用する欠陥追跡システムを使用して、ITがソフトウェアに対して欠陥レポートを入力できるようにすることをお勧めします。そうすれば、たとえば、特定のフォルダ内のファイルを削除する必要があり、1週間分だけ保持する必要があると言われなかった場合、「アプリケーションがディスクをログファイルでいっぱいにする」という欠陥を入力できます。 "、そしてそのフォルダを削除するための文書化された手法でITと協力することを提案します。

2
John Saunders

ドキュメントの要件の私のリストは次のようになります(特定の順序ではありません):

(ドキュメント:)

  • すべてのコマンドラインスイッチ
  • すべての終了状態と戻り値
  • ログメッセージ(内容はそれほど多くありませんが、構成できない場合はフィールドを説明します)
  • 構成構文
  • 設定ファイルのスイッチ
  • メモリ使用量
  • スレッドですか、それともフォークですか
  • サーバーが反応する信号は何ですか
    • サーバーを再起動しないが、構成を再読み取りする信号はありますか
    • それはどのように動作しますか? (既存のスレッド/プロセスが古い構成で終了するのを待ちますか?それらを強制終了しますか...)
  • クリーンでないシャットダウンで何が起こるか(特にそれが何らかの永続性サービス/サーバーである場合)
  • システムが提供する呼び出しを介してログを記録しますか、それともApacheとアクセスログの場合はそれ自体で書き込まれたもの(yuck)でログを記録しますか?私は明らかにオンボードツールを好みますロギング)
  • ネットワークサービスの場合、IPv4およびIPv6対応
  • トランクに関するドキュメントと特定のバージョンに関するドキュメント
    • configオプションはトランクでのみ使用可能であるため、無視されることを確認するために何時間も設定するほど悪いことはありません。
  • どの構成オプションがどのバージョンで有効か(v1.0以降で使用可能、v1.2以降で非推奨)

このようなドキュメントは、優れたドキュメントの例です。

私はこのようなドキュメントは失敗に満ちていると思います:

また、FreeBSDハンドブックは、ドキュメントの優れた例であり、OpenBSDのアプローチです。彼らは適切に文書化されていないものを追い出します。

編集:このリストは決して完全ではありません。すぐに頭に浮かんだのは基本的なものだけです。また、ドキュメントは、誰かが投げたように読むだけでなく、よく読める必要があります

2
serverhorror

要するに、私が指定して契約しているドキュメントを期待しています。

あまりにも多くの場合、この重要な詳細は合意から外されています。エンドユーザーはそれを期待しており、もちろん無料でそれを望んでいます。優れた開発者は、プロセスの早い段階でこの見落としを修正し、価格と時間の要件を含む期待を設定します。

1
Jim C

アプリケーションで適切なリリースノートを作成することは良いスタートです。リリースで現在の動作に変更があった場合、依存関係または開始/停止動作の変更、依存サーバーまたはデータベースへの負荷の変更などに関するQAからのメモ。

0
Cawflands

@Spoike(まだ回答にコメントできません。)

IT実装者(役割は会社の種類と規模によって異なります)は、次のことを達成するために一貫して作業する必要があります。

  • インストール/ターンオーバーの最小要件-言い換えると、ITは受動的ではなく、開発者がインストール/ターンオーバー時に必要な情報を「知っている」ことを期待できます。私は、アプリの適切なドキュメントを構成するものに関して、ITにかなりの混乱/意見の不一致があることがよくあることを発見しました。 Devは要件を理解しており(私たちは願っています)、IT部門は、少なくとも何が必要かを見つけるために党員集会を開く必要があります。

  • インストール/ターンオーバー手順-エンタープライズ設定では、これを変更管理またはガバナンスと呼ぶことがありますが、これは基本的に標準のレビューサイクルであり、IT部門はDev PRIORトップインストールに座って製品の概要を説明し、そのニーズ。

アプリのインストールは、舞台作品のデビューと同じです。幕が上がる前に、ディレクター(リード開発者)はステージ制作チーム(IT実装者)と繰り返し会い、オープニングナイト(パブリックインストール)のすべてが「ちょうどいい」ことを確認します。

開発者のペルソナを変更することはできませんが(なぜ変更したいのですか?)、すべてのユーザーに対して非常に高速に実行される素晴らしいアプリという共通の目標を示すことができます。コンセンサスITドキュメント要件は、それを保証するために必要なものの1つにすぎません。

0
Netais LLC

ITは、どのようなドキュメントが必要かを開発者と通信する必要があると思います。これを行うための最良の方法は、ITが必要なものに対応できるように、ITがプレイおよびテストするためのソリューションのプレリリースバージョン(またはイテレーションリリース)を開発が提供する場合です。

0
Spoike