GOST 34に準拠したドキュメント*-簡単です

今日は、プロジェクト文書の国内標準について話します。 これらの標準が実際にどのように機能するか、なぜそれらが悪いのか、何が良いのか。 公的および深刻な個人顧客向けのドキュメントを開発する場合、通常、選択の余地はありません。標準の遵守は、TKのドキュメント化の要件に含まれています。 実際には、標準の構造に関する誤解のさまざまな例、文書の内容、およびこれらの文書が必要な理由に対処する必要がありました。 その結果、技術的な作家、アナリスト、および専門家のペンの下から、そのような真珠が出てきて、彼らがどのような意識の状態で書かれたかがはっきりしないことがあります。 しかし、実際には、すべてが非常に簡単です。 Habréでの検索では、このトピックに関する全体的または多かれ少なかれの資料へのリンクは返されなかったため、この迷惑なギャップを埋めることを提案します。

ドキュメントの標準とは何ですか？

問題の34シリーズには、ドキュメントの主要な標準が3つしかありません。



GOST 34.602-89自動システムの作成に関する参照条件



TKの開発で最も愛され人気のある標準。 忘れてはならない唯一のことは、シリーズの他の標準と密接に関連していることです。この標準に従って実行された作業の声明を受け取った場合、直接の要件がない場合でも、他の標準に従うことを強くお勧めします。 少なくとも一般的なイデオロギーの観点から（以下について）



GOST 34.201-89自動システムを作成する際のドキュメントの種類、完全性、および指定



これは、GOST 34のドキュメントの完全なリスト、ドキュメントのコーディングに関する推奨事項、プロジェクトドキュメントのどのステージに関連するか（ステージはGOST 34.601-90で説明されています）、およびそれらを互いに組み合わせる方法を提供する基本ドキュメントです。



実際、この標準はコメント付きの大きなテーブルです。 使いやすくするためにExcelに取り込むことができます。



RD 50-34.698-90自動システム。 ドキュメントコンテンツの要件



プロジェクト文書の内容を説明する詳細度の異なる大量の標準。 インデックスとして、前述のGOST 34.201-89が使用されます。



標準のRD 50-34.698-90には、多くの質問とその規定の解釈がありますが、それらはあいまいであるため、顧客と請負業者、またはプロジェクトチームのメンバーによっても異なる方法で理解されることがよくあります。 しかし、残念ながら、これ以上具体的なものはありません。



次に、伝統的に短所から始めて、標準の長所と短所を検討します。

規格の短所

メインのマイナスは誰にとっても明らかです-標準は古いです。 彼らは、自動化システムのアーキテクチャについて時代遅れの見方をしています。 例：

• クライアントプログラムとDBMSサーバーで構成される2レベルアプリケーション（3つ以上の「層」アプリケーション、WeblogicまたはJBossなし）
• 説明したように、データベーステーブルの構造は、論理データモデルのアイデアを提供します（アプリケーションとデータベースの間にHibernateが存在する可能性があり、それがひどく過剰に見えたという事実）
• ユーザーインターフェイスは単一ウィンドウです（本当に違うのですか？また、「ブラウザー」とは何ですか？）
• システムにはレポートがほとんどありません。それらはすべて紙であり、マトリックスプリンターで印刷されます。
• 開発中のプログラムは、明確な入力と出力を持ち、高度に専門化された「情報処理問題」の解決に焦点を当てています。 情報処理の基礎は「アルゴリズム」です。 時にはいくつかの「アルゴリズム」があります。 （その後、オブジェクト指向プログラミングは最初のステップのみを取り、真剣に考慮されませんでした）。
• データベース管理者は、テーブルに含まれる情報を理解し、システムディレクトリの編集に積極的に関与します（実際には、50の異なるアプリケーションに対して1つのDBMSサーバーがありますか？）

したがって、標準には次のようなアーティファクトがあります。



5.8. ()

50-77 .







この文書の意味は、ソビエト企業がいわゆる「印刷サイト」を使用したということです。そこでは、エンジニア自身がよく書くドライバーであるドットマトリックス高速プリンターがありました。 そのため、印刷されたドキュメントが適切に表示されるように、印刷が必要なすべてのドキュメントの登録簿を維持する必要がありました。



「ビデオフレーム」は、テキストディスプレイに表示されたドキュメントでもあります。 ディスプレイは、必要な文字と必要な数の文字を水平および垂直方向に常にサポートしていませんでした（グラフィックはまったくサポートされていませんでした）。 したがって、ここでも、画面上のすべてのドキュメントのフォームを追加で調整する必要がありました。



現在、「machineogram」、「video frame」、「ATsPU」という言葉は何も語りません。 90年代に専門機関を卒業しましたが、それらが使用されていることもわかりませんでした。 これは、Windows 3.1、VGAディスプレイ、3インチフロッピーディスク、および最初の国内インターネットサイトが登場したときです。 しかし、標準にはこれらの言葉があり、顧客は時々GOST 34.201-89に基づいて完全なドキュメントセットを提供するように気まぐれに要求します。 さらに、TKのこのような文言は、省から省へとさまようものであり、実質的な部分が駆動される、書かれていないテンプレートのようなものになっています。



したがって、プロジェクト内の「ドキュメントのフォーム（ビデオフレーム）の描画」という愚かなタイトルのドキュメントは、空であってはなりません。

標準では何が良いですか？

顧客と請負業者が同じ言語を話すことができ、少なくとも顧客が送信された結果に対して「クレーム」を持たないことを保証するという点で、どの標準もすでに優れています。



また、GOST 34規格は優れた人々によってコンパイルされ、長年にわたって展開され、明確な目標を持っているため、優れています。ACSが紙上で表現する複雑な抽象的なエンティティを可能な限り完全に記述することです。



GOSTを聞いたことがない欧米の請負業者にタスクを正しく設定する必要がある場合は、これらの標準、より正確にはその内容であるセマンティックコンポーネントにも依存できます。 繰り返しますが、情報の完全性を保証することには大きな価値があるからです。 高度なプロフェッショナリズムでどのように楽しもうとしても、要件に基本的なものを含めることを忘れることがありますが、同じGOST 34.602-89はすべてを「覚えています」。 西洋の請負業者の仕事の結果がどのように見えるか理解できない場合は、文書化の要件と推奨されるセクションをご覧ください。 思い付かないで、思いつかないほうがいい！ 最もありそうなのは、私たちの標準に西洋のものがあり、すべてがより充実し、より現代的で、より良いものになる可能性があることです。 残念ながら、GOSTだけでは不十分なケースはこれまでになかったため、私はそれらに精通していません。



標準の作成者は、javaや.NET、HDモニター、インターネットについて何も知らなかったという事実を笑うことができますが、彼らが行った作業の規模と私たちの専門コミュニティに対するその価値を過小評価することはお勧めしません。

GOSTシリーズ34に準拠したドキュメント標準の読み方と理解方法

標準では、すべてのドキュメントが時間とサブジェクト領域の2つの軸に分割されます。 GOST 34.201-89の表2を見ると、この区分をはっきりと見ることができます（「作成の段階」列と「プロジェクトの一部」列

ACSを作成する段階

作成の段階はGOST 34.601-90で定義されています。 それらの文書化には3つの関連性があります。

• 予備設計（EP）
• 技術プロジェクト（TP）
• 作業文書（RD）の開発

予備設計は、参照条件の段階に従い、予備設計の決定を下すのに役立ちます。



技術プロジェクトでは、将来のシステムをあらゆる角度から説明します。 TPステージの文書は、読んだ後、提案されたアプローチ、方法、アーキテクチャおよび技術的ソリューションの完全な明確性を残すべきです。 次のフェーズでは、アプローチを説明し、技術的解決策を正当化するのは遅すぎます。そのため、Pフェーズは、TORのさまざまな要件がフェーズPのドキュメントに反映される必要があるため、作業を正常に完了するための鍵となります。ステージPでは、システムがまったく存在しない可能性があります



ワーキングドキュメントは 、新しいシステムの展開、試運転、およびさらなる運用を目的としています。 これらは、将来の素晴らしさを説明するフェーズPとは対照的に、物理的に既存のエンティティを説明する非常に具体的な情報を含むドキュメントです。

ACSを作成するための設計ドキュメントの一部（セクション）

サブジェクト領域は「担保」に分割されます。 最初は、このような分割は冗長で不要なようです。 しかし、このツールキットを実際に使用し始めると、それに組み込まれたイデオロギーが徐々に伝わります。



GOSTによってコンパイルされた自動システムは、特定のアルゴリズムに従って異なるソースからの情報を処理し、ドキュメント、データ構造、または制御アクションの形式で処理結果を提供するハードウェア、ソフトウェア、および通信チャネルの組み合わせです。 最も単純なオートマトンのプリミティブモデル。



この「オートマトン」を完全に説明するために、次のセクションが作成されました（図のように）。



質問に答える数学サポート（MO） ：「ブラックボックス」内にどのロジックが縫い付けられていますか？ なぜこれらのアルゴリズム、正確にそのような式と正確にそのような係数が選択されるのですか？



ソフトウェアは、プロセッサまたはデータベースについて何も知りません。 これは別の抽象的な領域であり、「真空中の球状の馬」の住まいです。 しかし、このソフトウェアはサブジェクト領域、つまり現実の生活と非常に密接に関連しています。 たとえば、交通制御システムの制御アルゴリズムは、顧客が合意する前に、交通警察で合意する必要があります。 そして、あなたはそれらが別の小さな本に割り当てられている理由を理解します。 アプリケーションサーバーが動作するOSのトラフィックポリスには誰も興味がないのですが、雨や雪の中でスコアボードに表示されるサインと速度制限は非常に興味深いからです。 彼らは自分の部分に責任があり、他に署名するつもりはありません。 一方、彼らが署名したとき、質問の技術的な側に質問はありません-他のディスプレイや信号機ではなく、なぜ彼らが選んだのでしょうか。 「先祖」の知恵は、そのような実際的な場合にのみ現れます。



情報サポート（IO） 。 システムの別のスライス。 今回は、システムのブラックボックスが透明になり、その中を循環する情報を確認します。 他のすべての臓器が見えないときの人間の循環系のモデルを想像してください。 このようなものが情報サポートです。 情報フローの内外への構成とルート、システム内の情報の論理的編成、ディレクトリとコーディングシステムの説明（プロダクション用プログラムを作成した人はどれだけ重要かを知っている）について説明します。 主な物語はTP段階にありますが、一部の「痕跡」は、ドキュメント「データベースディレクトリ」のようにRD段階に流れます。 以前はタイトルに書かれていたものが正確に含まれていたことは明らかです。 しかし今日、非常に頻繁に購入したサブシステムとその不可解な情報ストレージがシステムの一部として使用される場合、複雑な統合システム用のドキュメントを作成してみてください。 私は、このドキュメントが現在特に必要ではないという事実については話していません。



または、ここに「マシンストレージメディアのお知らせ」があります。 フィルムを備えた多数の磁気ドラムまたはリールがあったことは明らかです。 さて、何をそこに持ってくるのでしょうか？



要するに、RDフェーズでは、情報サポートドキュメントは正式なものである必要があるため、かなり悪意のある初歩的なものですが、それを埋める内容は何もありません。



ソフトウェア 。 設計ドキュメントの好きな部分。 はい、たった1つのドキュメントであるという理由だけで！ そして、誰もがそこに記録する必要があるものを理解しています。 しかし、それにもかかわらず、私は繰り返します。



このドキュメントでは、IEで説明されている情報を処理するMOで説明されているアルゴリズムを実行するために使用されるソフトウェアツールについて説明する必要があります。 つまり、ここで他のセクションからの情報を複製する必要はありません。 システムのアーキテクチャ、選択したソフトウェアテクノロジーの理論的根拠、それらの説明（プログラミング言語、フレームワーク、OSなど、あらゆる種類のシステムに関するもの）を提供します。 また、このドキュメントでは、情報処理ツールの構成方法（メッセージキュー、ストレージ、バックアップツール、アクセシビリティソリューション、あらゆる種類のアプリケーションプールなど）について説明します。 標準には、このドキュメントの内容の詳細な説明があり、専門家なら誰でも理解できます。



テクニカルサポート（TO） 設計ドキュメントの最愛の部分。 虹の絵は、開発が必要な豊富な文書によってのみ影が薄くなります。 合計では、標準に従って、22の文書を作成する必要があり、そのうち9がTP段階にあります。



実際には、この規格は、コンピューターハードウェアとネットワーク、エンジニアリングシステム、さらには建設部品（必要な場合）を含むすべての技術サポートの説明を提供します。 そして、この経済は膨大な数の基準と規範的行為によって規制されており、異なる組織で調整されているため、すべてを部分に分割し、部分で調整（編集）する方が便利です。 同時に、この標準では、いくつかのドキュメントを相互に結合することができます。これは、1人の人が全体に同意する場合に意味があります。



また、品質基準のセットは技術文書の会計と保管を意味し、顧客の「書籍」は説明の主題に応じて異なるアーカイブに入れることができることも忘れないでください。 これは、ドキュメントの破壊を支持するもう1つの議論です。



組織のサポート（GS） 技術者にとっては普通のことですが、できるだけ早くこのセクションをすり抜けたいという欲求をそれ自体で抑制したので、反対に、私はそれをより詳細に検討します。 同僚たちは、最近、このセクションの説明を必要とするプロジェクトに悪い傾向がありました。



TAステージでは、このセクションには「 組織構造の説明 」というドキュメントが1つだけ含まれています。このドキュメントでは、組織構造の変更に関して何を準備すべきかを顧客に伝える必要があります。 突然、システムを運用したり、新しい役職を導入したりするために、新しい部門を編成する必要があります。



RDの段階では、別の興味深いドキュメントが表示されるので、個別に検討したいと思います。



ユーザーマニュアル 。 コメントは不要だと思います。



コンピューター支援設計の方法論（テクノロジー） 。 必要に応じて、このドキュメントにソフトウェアアセンブリプロセス、バージョン管理、テストなどの説明を記載できます。 しかし、これは、ToRで顧客がソフトウェアを個人的に組み立てたい場合です。 彼がそれを必要としない（そしてそれを支払わない）ならば、あなたの内部の台所全体は彼の仕事ではなく、この文書は行われる必要はありません。



技術指導 。 ビジネスプロセスを形式化するための方法に関連して、cな顧客は、運用サービスの運用手順をこのドキュメントに詰め込もうとすることがあります。 したがって、これは決して必要ではありません。



ビジネスプロセスの説明、役割と職務の説明、労働規制-これらはすべて運用上の文書、つまり組織的および管理上の文書です。 これはコンサルティングプロジェクトの成果であり、私が理解しているように、あなたから購入したものではありません。 そして、あなたはあなたから技術プロジェクトを購入しましたが、そのドキュメントも技術的なものです。



技術マニュアルは、ODSとユーザーマニュアルの間のレイヤーです。 RPは、システムで特定のアクションを実行する方法を詳細に説明します。 技術マニュアルには、システムの操作に関連する特定のケースで実行する必要があるアクションが記載されています。 大まかに言って、技術マニュアルは特定の役職や役割についてのRPの短い要約です。 顧客に役割がない場合、または顧客に役割と職務要件を作成してもらいたい場合は、最も基本的な役割を文書に含めます。たとえば、オペレーター、上級オペレーター、管理者。 「気に入らない」または「気に入らない」というトピックに関するお客様のコメントには、役割と職務内容のリストを添付する必要があります。 私たちはビジネスプロセスを設定しないからです 。 これらのビジネスプロセスを自動化します。



これは「国民経済」のさまざまな部門で繰り返されるのは初めてではないため、説明されているレーキについて、カラフルな例を使用して個別に記述します。



データ処理の技術プロセスの説明（テレプロセッシングを含む） 。 特別に指定された「コンピューターオペレーター」がマシンパンチカードを送り、結果の印刷物を封筒に詰めたときの、洞窟時代の悲惨な初歩。 この指示は彼らのためです。 21世紀に何を書けばいいのか、はっきりとは言えません。 出て行け。 最善の方法は、このドキュメントを単に忘れることです。



システム全体のソリューション（OR） 。 この規格では、PRセクションの17のドキュメントを規定しています。 第一に、これらはほぼすべて、予備設計の予備段階の文書です。 第二に、これらはすべての種類の推定、計算、および自動化された機能の簡単な説明です。 つまり、人々の情報はメインのITプロダクションからではなく、サポートスタッフ（管理者、見積者、調達スペシャリスト、エコノミストなど）からのものです。



そして第三に、PRの構成には、「技術プロジェクトの説明」というタイトルのメガドキュメントが含まれます。これは、想像されるとおり、エグゼクティブサマリーであり、実際、多くのデザイナーがTPステージのすべての有用なコンテンツをその中に押し込みます。 このような急進的なアプローチは正当化でき、顧客と請負業者の両方にとって相互に有益な場合もありますが、場合によってはそうです。



GOST 34の使用のバリエーション

1. 標準への完全かつ正確な遵守 。 もちろん、自発的に、誰もそのようなドキュメントのクラウドを作成しません。 そのため、顧客の緊急の要求がある場合にのみ、完全な文書セットが作成されます。顧客は作業明細書でこれを確保し、契約によって打ち切られました。 この場合、文字通りすべてを理解し、GOST 34.201-89の表2のドキュメントの名前が記載された物理的な「書籍」を顧客に提供する必要があります。ただし、絶対に不要なものは除きます。 また、ドキュメントの内容は、想像を絶することなく、セクション名までRD 50-34.698-90に準拠する必要があります。 顧客が脳を爆発させるために、大規模なシステムがサブシステムに分割され、サブシステムごとに個別のプロジェクトドキュメントが発行される場合があります。 それは威圧的に見え、地上の精神の助けを借りて通常の制御を受けることはありません。 特にサブシステム統合の観点から。 これにより、受け入れが大幅に簡素化されます。 主なことは、あなた自身が混乱することはなく、システムは正常に機能することです。
2. GOSTが大好きです 。 標準のような深刻な大企業。 人々がお互いをよりよく理解するのを助けるからです。 顧客が注文と標準化を好むことに気づいた場合、ドキュメントを開発するとき、TKを必要としない場合でも、標準のGOSTイデオロギーに従うようにしてください。 調整スペシャリストはあなたをよりよく理解し、承認しますが、ドキュメントに重要な情報を含めることを忘れないでください、ドキュメントのターゲット構造をよりよく見て、より正確にそれらを書くための作業を計画し、あなた自身とあなたの同僚に多くの神経とお金を節約します。
3. すべてが機能していれば、ドキュメントについては気にしません 。 無責任な顧客の姿が消える。 ドキュメンテーションの同様の見方は、小規模で貧しい顧客の間でも、ボスが忠実な友人-ディレクターに囲まれているペレストロイカの時代から残された権威主義的な「イディオクラシー」でも見ることができ、すべての問題は個人的な会話で解決されます。 このような状況では、一般的にドキュメントをhammerすることは自由ですが、結局のところ、視界を撃ち落としてはならず、少なくともドキュメントをコンテンツで概略的に埋めておく方が良いでしょう。 この顧客にない場合は、次の顧客に引き渡します（販売）。

おわりに

この記事は、ACSを文書化するためのGOSTに関するものでした。 GOSTは古いですが、結局のところ、家庭では非常に便利です。 いくつかの明らかな初歩を別として、ドキュメンテーション構造には完全性と一貫性の特性があり、標準に従って多くの設計上のリスクを取り除きます。



提示された資料があなたにとって有用であるか、少なくとも興味深いものであることを願っています。 面倒な退屈にもかかわらず、文書化は重要で責任のある仕事であり、その正確さは優れたコードを書くときと同じくらい重要です。 良い文書を書いてください、同僚！ 来週は2回連続して出張しますので、新しい資料の発行を保証することはできません（私はザパシュニクを持っていません。頭から書いています）。