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


8

タイトルは本当にすべてを語っています。

最終的には、開発とITがこの種の事柄について頭を悩ませることになるかもしれません。1つまたは複数のサーバーで実行されているソリューションのインストール、パッチ適用、保守、開始、停止、および診断が予想される場合、どのレベルのドキュメントが予想されますか?


回答:


9

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

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

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

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

保守:通常の動作と異常な動作がどのように見えるかを文書化します。監視する必要のあるキューやその他の事項、およびこれらの通常の範囲を文書化します。

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

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

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

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

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

ダウンして起動する:方法、順序、特別な手順(たとえば、サーバーがシャットダウンする前に接続をドレインできるようにする)。

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


1
うわー、展開前のシステムに関するこのレベルの知識は、ドキュメントを気にせず、すごいでしょう。これは、一部の企業が開発者にこのように考えるのではなく、開発者と共にSREを採用する理由ではないでしょうか。
Cawflands 09年

ほとんどの開発者がそのようなことを考えていないのは本当です(私はソフトウェア開発者として、また後にインフラストラクチャ管理会社のアーキテクトとして働いたことがあり、後者は目を開かせました...)。開発者はこれらのトピックについて知っておくべきだと思いますが、知らない場合は、一緒に作業する専門家が先に進む方法かもしれません。これは実際には、ソフトウェアで重要なことについての幅広い問題の一部です。価値は、実行されて利用可能なソフトウェアであり、機能だけでなくサービスを提供することです。さらに詳しくお答えできるように、別の質問をする必要があるかもしれません:)
典型的なポール'05

2

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

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


うん、そこにいて、それをやった。開発者が無制限に拡大していた3つのテーブルをパージする方法を私たちに伝えるのに4週間かかりました。事前にそのことを考えた方が早い。しかし、管理性の問題はソフトウェアの欠陥であるという点について、私は強く同意します...
典型的なポール

私は通常、文書化されていないサーバー(デーモンなど)のデプロイを拒否します。私が本当にそれらを強制的に展開する必要がある場合(管理はそれを要求します)すべてのものを理解するのにどれくらいの費用がかかるかを明確に述べます
Martin M.

2

ドキュメントの要件のリストは次のとおりです(特定の順序ではありません)。

(上のドキュメント:)

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

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

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

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

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


1

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

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


0

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


0

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


0

@スポイケ(まだ回答にコメントすることはできません..)

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

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

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

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

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

弊社のサイトを使用することにより、あなたは弊社のクッキーポリシーおよびプライバシーポリシーを読み、理解したものとみなされます。
Licensed under cc by-sa 3.0 with attribution required.