そして有用なドキュメントの作成を開始します
非常に大規模なシステムインテグレーターでさえ実装されているITインフラストラクチャプロジェクトの大部分には、1つの重大な欠点があります-役に立たないプロジェクトドキュメント。 もちろん、ドキュメントには必要なすべてのデータが含まれており、それを読んだ後、何がどのように編成されたかを把握できます。 その無益さは、情報システムのさらなる運用中に現れ、現在の状態で文書を維持することの困難さと、その中に必要な情報を迅速に見つけることができないことで表されます。 その結果、このプロジェクトのドキュメントは、時間の経過とともに、有用な参考資料ではなく、別の美しく無駄なレポートドキュメントになります。
この記事では、仕事で使用するプロジェクトドキュメントをコンパイルするためのいくつかの原則を同僚と共有したいと思います。おそらく、お客様が構築した高品質のITインフラストラクチャを楽しむだけでなく、ドキュメントを最新かつ簡単に最新の状態に保つことができますその上で、何年も優しい言葉であなたを覚えています。 続行：
1）構造情報
ドキュメントは、プロジェクトの配信段階でのみ、ほとんどの場合完全に読み取られます。 文書の短い質問への迅速な回答を提供する能力に応じて、「このサーバーは何をしますか？」、「メールはどのように機能しますか？」、「このハードウェアをオフにすると機能しなくなりますか？」 ドキュメントの明確な構造により、必要な情報の検索が大幅に簡素化されます。 たとえば、次の構造を順守しています。
1.ネットワークの一般的な説明
2. ITインフラストラクチャ
- ネットワーク機器
- 物理サーバー
- ストレージシステム
- 仮想マシン
- 周辺機器
- オフィス機器
- ...
3. ITサービス
- Active Directoryドメインサービス
- WSUS更新サーバー
- WDSユーザーワークステーション展開サービス。
- 郵便
- ドキュメントとのコラボレーション
- 電話接続
- インターネットアクセス
- ...
4.アプリケーション
- ソフトウェアライセンス
- 命名規則
- ...
2）ドキュメントの作成者を決定する
ITインフラストラクチャの説明-1つのドキュメント、指示-別のドキュメント。 1つのドキュメントに、印刷サービスの説明、プリンターへのアクセス権を付与する手順、およびMFP上のドキュメントをスキャンする手順を収めようとしないでください。 ITインフラストラクチャの説明、テクニカルサポートスペシャリストの指示、ユーザーの指示の3つのドキュメントを作成することをお勧めします。 この場合、システム管理者、enikeyschik、およびユーザーは、「余分な情報」のページをひっくり返すことなく、必要な情報を正確に受け取ります。
3）データの完全性、完全性、および均一性を達成する
デバイスまたはサーバーの説明のドキュメントで何らかの技術的なパラメーターが示されている場合、適用可能なすべての要素について示される必要があり、ドキュメントのどこでもこのパラメーターは同じと呼ばれるべきです。 将来、ネットワークでいくつかの変更を行う必要がある場合（たとえば、DNSサーバーのアドレスを変更する場合）、ドキュメントを簡単に検索することで、設定を変更する必要があるノードの完全なリストを作成し、それによって変更を正確に計画することができます。 些細なことのように思えますが、ドキュメントの利点は大幅に増加します。
4）情報の重複を避ける
ITインフラストラクチャの変更が将来ドキュメントに簡単に反映されるように（そしてそれによって最新の状態に保つには）、その情報を1か所でのみ変更する必要があります。 つまり サーバー、デバイス、またはアプリケーションのパラメーターの値は、ドキュメント全体に対して1回指定する必要があります。 ドキュメント内の3つの場所で、そのようなサーバーがそのようなIPアドレスを持っていることを示した場合、このドキュメントで数年後にサーバーが3つの異なるIPアドレスを持ち、ドキュメントが元の値を失う可能性があります。 そのような場合、ドキュメント検索を使用する人はめったにいません。
5）テクノロジーを説明または宣伝せず、比較の勢いを使用しない
一部の企業のプロジェクト文書は、商業的なオファーに基づいて作成されているように思えます。 後でドキュメントを読むスペシャリストにとって、導入時のこの技術やその技術がいかにクールであったか、あるいは選択の理由は関係ありません。プロジェクトは既に完了しており、現在はすべてがどのように設定されたかに関する情報を取得するだけです 「高可用性」、「柔軟性の向上」、「信頼性の向上」というフレーズは、ドキュメントのコンパイラーの個人的な評価判断にすぎません。
6）テキスト単位で意味の集中度を高める：テーブルとリストを使用する
私が会わなければならなかった最悪のプロジェクト文書は、オープニングエッセイのようなものでした。 3ページ目のどこかで、IPアドレス、マスク、アレイ、ユーザーサービス、およびアクセスログインとパスワードが結合されました。 そのようなドキュメントで必要なパラメーターを見つけるには、次の文で必要な値に到達することを期待して、テキストのいくつかの段落を読む必要がありました。
ドキュメントでトピック以外の単語を使用するのを少なくしてください。 テーブル内のすべての関連する値を作成し、リストを実行する代わりにリストを作成すると便利です。これにより、多くの場合、セクションをただ見回すだけで、目的のパラメーターをすぐに見つけることができます。
7）プレゼンテーションの1つの言語とより少ないブルシタ
「バックアップ」ではなく、「バックアップ」。 アンチウイルスではなく、アンチウイルスソフトウェア。 「ホットフィックス」（元のスタイルは保持されます）ではなく、「フィックスパック」。 ここではシンプルなもののようで、ドキュメントを読むと脳が壊れなくなります。
8）製品のフルネームを示す
彼らは今、「SUSサーバー」または「RISサーバー」について何か言っているのですか？ ドキュメント内のソリューションの省略名を自給自足の指定として使用する前に、約5〜10年以内に技術専門家に何か話をするかどうかを考えてください。 たとえば、これらのソリューションを「SUS（ソフトウェア更新サービス）インストールサーバー」または「RIS（リモートインストールサーバー）ネットワークインストールサーバー」と指定する方がはるかに適切です。
9）スクリーンショットの補足ですが、テキスト情報は置き換えません
読者が初めてアプリケーションをよく見るユーザーマニュアルでは、スクリーンショットは単にテキストに添付するために必要です。 読者が危機にwhatしているものをすでに知っているはずのITインフラストラクチャのドキュメントでは、ほとんどの場合、スクリーンショットは有用な情報を伝えずにスペースを占有します。 ただし、どちらの場合も、スクリーンショットでテキスト情報を置き換えることはできません。 まず、特にドキュメントを印刷した後、彼らはまだ何も見ることができません。 次に、設定を変更するには、ドキュメントの関連性を維持するために2番目のスクリーンショットを撮る必要があります。 最も重要なのは、スクリーンショットの値がドキュメントを検索しても見つからないことです。
10）機器の視覚的な図と写真を使用する
ネットワークの機能図、ラック内の機器の位置、および機器自体の外観は今ではドキュメントに追加および追加するのがそれほど難しくありませんが、HP Proliant G8サーバーがどのように見えるかがすべての管理者にわかるわけではないため、5-6年後に必要なハードウェアの検索が大幅に簡素化されます2014リリース。
11）文書を注意深く読んでください。 テキストにエラーがないか確認してください！
「顧客のモスクワオフィスでの集中ユーザー印刷は、ネットワークプリンターサービスを使用して行われます」という形の売り上げによって、IT技術の能力についてどれだけ知っているかを真剣に考えることがあります。 まあ、私は一般的にスペルと句読点のエラーについては沈黙していますが、私自身はロシア語でトリプルを持っていました。 文書をクライアントに送信する前に、いくつかの単語とブックマークを異なる場所に追加して、文法を多少理解している人に読んでもらいます。 彼がすべてのブックマークを見つけた場合-仕事はうまくいきましたが、ブックマーク内のわいせつな言葉を使って行き過ぎないようにすることが主なことです-時にはドキュメントがクライアントとともに残されます。
頑張って！
イワン・コルマチェフ
IT部門会社
www.depit.ru