アントワーヌドサンテグジュペリ
ユーザーマニュアルの開発の多くは、GOSTによって規制および説明されています。 しかし、大規模な異種システムを作成する場合、これらのドキュメントでは完全にカバーされていない疑問が生じる場合があります。
ユーザーマニュアルに対する態度は異なります。 多くの人は、大規模な異種情報システムを開発する過程でドキュメントの場所と役割が何であるかをまったく気にしませんが、他の人にとってはすべてが非常に明確です。 急がないでください。 この記事では、この重要なドキュメントを作成して最新の状態に保つプロセスを整理するアプローチを検討し、情報システム全体に対するユーザーマニュアルの重要性を評価し、予想外の結論に至ります。
この記事は、テスター、テクニカルライター、アナリスト、さらにはプロジェクトマネージャーにも役立ちます。
問題の説明
しばらく前、私はアナリストとして、連邦レベルの情報システムを開発するプロジェクトに取り組み始めました。 サブジェクト領域にすばやく浸るために、ユーザーマニュアルを取り上げる必要がありました。監査を実施し、システムの機能を急速に拡張するためにドキュメントを完成させるプロセスを整理します。
議論されるアプローチと原則は、特に以下の条件に合わせて開発され、適応されているため、プロジェクトの機能については別に説明します。
1. スケール。
相互作用する多数のサブシステムを含む大規模な異種分散情報システム。
2. 並行開発 。
システムのサイズが大きいため、アナリスト、開発者、およびテスターの隔離されたチームがシステムに取り組んでいます。
3. 頻繁な変更 。
繰り返しますが、規模の結果は、絶え間ない変化と改善の流れです。
4. プロジェクト内の比較的普遍的で標準化された一連のビジネスプロセス。
ほとんどのプロセスには、他のビジネスプロセスと同様の一定の部分があります。
現在のバージョンのユーザーマニュアルをざっと見ても、ドキュメントの品質が低いことについて結論を出すことができました。 2つの主な問題がありました：類似の機能とプロセスの記述における無関係性と均一性の欠如 。
ユーザーガイドの質の低さは、プロジェクト全体に多くのマイナスの結果をもたらす可能性があります。 主なものを強調します。
- システムの不適切な使用による運用コストの増加、およびその結果、サポートサービスの負荷の増加。
- 顧客と顧客の不満;
- システムの開発と保守のコストが増加しました。
状況を修正することが急務でした。 そして、これを最小限のコストで実現します。
ソリューションを検索する
各問題に対して個別のアプローチが開発されました。 各問題と各アプローチをより詳細に検討します。
文書の無関係性
ドキュメントの無関係性には、2つのクラスの問題が含まれています。利用可能な機能の古い説明と、新しいシステム機能の説明の欠如です。 問題を解決するためのアルゴリズムは、次のように選択されました。
- IS ISモデルの説明（つまり、現在あるもの、説明されている機能およびビジネスプロセス）を作成します。
- TO BEモデルを説明します（各サブシステムの主要なアナリストがコンサルタントとして関与しました）。
- 「トラフィックライト」インジケータを使用して「現状のまま」と「今後」を比較し、アクションプランを作成します。
便宜上、データはテーブルに入力され（図1を参照）、その行は自動化されたプロセスと機能を示し、列はユーザーマニュアルの既存の説明です。 後者は、各サブシステムのブロックにさらにグループ化されました。 その結果、プロセス/機能の対応関係とその説明が明確になりました。 さらに、さらにグループ化するために同様の説明を識別することができました。
その後、すべての説明のカタログ化が実行されました（説明の総数が100個を超えたため、緊急の問題です）。 プロセスがユーザーマニュアルに記載されている場合、対応する行と列の交点にあるセルに、アイテム（セクション）の番号が付けられています。
さらに、比較結果は、視覚的なインジケータ「トラフィックライト」によって記録されました。
- 緑色-プロセスはマニュアル内にあり、ビジネスで必要です。
- 赤-プロセスはありますが、必要ではありません（削除！）。
- 黄色-プロセスはありませんが、必要です（追加！）。
- 灰色-プロセスは存在せず、必要ありません。
カラーインジケータを使用すると、全体像を明らかにすることができます。ユーザーマニュアルを編集する必要があります。
図1
ドキュメントの作業が開始されました。 この段階での助けは再びテーブルでした。プロセスが1つのブロックで編集されると、別のブロックで同様の方法で80％作成されます。
ユーザーガイドに記載されている機能の説明の総数は100を超えており、通常は25です。
説明をさらに処理するには、追加のグラデーションが必要でした。明るい緑色-すべてが正常で、編集が不要なシナリオの場合。 薄緑-一般的に正しく記述され、いくつかのポイントを修正するだけでよいシナリオの場合。 オレンジ-基本的に誤って記述されており、最初に編集する必要があるもの。
図2
その結果、全体的な画像は色付きで表示されました。問題のある領域のオレンジ色の斑点が多く見られ、明るい緑色が多く、明るい緑色がほとんどありませんでした。
ドキュメントの作業中のコンプライアンステーブル：
図3
「ペイント」作業が完了すると、優先順位が特定されました。
- オレンジ色を削除-すべてが正しく記述される必要があります。
- 明るい緑色のフィールドを明るい緑色にします。
この時点で、パレートの法則 （原則20/80）を思い出すことが重要です。最も問題のあるオレンジの領域を比較的迅速に修正し、長い間ライトグリーンで作業しました。 確かに、実際には、ユーザーがマニュアルを実際に使用できるように努力するかどうかがポイントです。
均一性の欠如
この問題を解決するためのタスクは、同様のプロセス（ケース）の記述の均一性を確保し、ドキュメントの更新と保守の人件費を大幅に削減することでした。 アプローチは、各プロセスの記述がビルディングブロック（1）の形式で提示され、ドキュメント自体-それらの組み合わせ（3）に応じて選択されました。 すべてのビルディングブロックは、必須の変更管理とバージョン管理サポートを備えたリポジトリ（Wiki）に配置する必要があります（2）。
図4
このアプローチの主な利点は、人件費の大幅な削減です。ビルディングブロックの共通部分を作成および編集するとき、編集は1回だけ行われます。 ビルディングブロックからユーザーマニュアルを組み立てることも、従来のバージョンに比べてはるかに高速です。
基本的に重要な点：リポジトリへのアクセスは、その使用に関する確立されたルールに従って、プロジェクトに取り組んでいるすべてのチームに提供されるべきです。
更新のためのこのアプローチと、アセンブリのための「ビルディングブロック」の方法を使用して、ドキュメントを短時間で適切な状態にすることができました。 従来の文書作成方法と比較して、人件費が30％以上削減されました 。 この時点で、ハッピーエンドを指定できるように思えますが、続けたいと思います。 面白いでしょう。
要件管理サイクルにおけるユーザーガイドの場所
高品質のユーザーマニュアルには新しい機能が追加され、要件管理システムおよび情報システムの全体的な開発サイクル（シーケンシャルまたは反復）に完全に統合されました。
要件の分析（1）からテスト（4）までの古典的な開発サイクルでは、ドキュメントを準備する段階が追加され、その中でユーザーマニュアルが特別な場所を占めます。 なぜこのドキュメントがそれほど重要なのですか？ いくつかの理由があります。 個々のサブシステムを並行して独立して開発する場合、統合が失われる可能性があります（たとえば、制御要素の場所、名前など）。 ユーザーマニュアルの準備中に、機能面とユーザーインターフェイスのレベルの両方で不一致/不一致が表示されます。
図5
ユーザーマニュアルのレベルでのみ、システムは全体として表示され、個別のサブシステムのセットとしては表示されません。 ビルディングブロックの概念により、不整合の問題を解決できますが、これは、参照パーツとして生産部品を開発するときにリポジトリを使用する場合のみです。 したがって、管理者には、アナリストとテスターという新しいユーザーカテゴリがあります。 そしてもちろん、ドキュメントは同期され、ユーザーの要件に完全に準拠する必要があります。 この段階で、追加の検証が実行され、ユーザー要件の開発機能に準拠しています（ユーザーマニュアルには、実際にはシステムのビジネス記述が含まれています）。
図5は、開発プロセスがガイドの作成によって最終化されることを明確に示しています。 このドキュメントは、開発の他の段階でも積極的に使用されています。
図6
結論
自動化された機能の最新の説明を含む定性的かつ有能に編集されたマニュアルは、エンドユーザーおよび開発者にとって重要かつ要求されるドキュメントとなり、いくつかの新しい機能を取得します。
- 知識ベースコンポーネント。
- 機能の追加テストおよび検証ライン、制御ツール;
- 情報システムの全体的な品質を改善する手段。
ユーザーガイドを作成するときに説明されているアプローチを使用すると、次のことができます。
- ドキュメントを作成して最新の状態に保つコストを大幅に削減します。
- ドキュメントを形成するプロセスを自動化する。
- ユーザーマニュアルを準備するプロセスを、情報システムを開発する他のプロセスと深く統合し、同期させる。
- 情報システム全体の品質を向上させます。
この記事を読んだ後、皆さんの一部がこの一見シンプルに見えるが、非常に重要な文書であり、その形成に考慮されたアプローチを採用することを再確認することを願っています。
PSこの記事には、ユーザーマニュアルの要素とセクションの内容の問題は含まれていませんでした。 これは、RD 50-34.698-9およびIEEE 1063-2001のサブセクション3.4で詳細に検討および規制されています。
文書の構造と内容オペレーターズマニュアル、プログラマーズマニュアル、システムプログラマーズマニュアルは、それぞれGOST 19.505-79、GOST 19.504-79、GOST 19.503-79によって規制されています。
リストされた標準の分析に基づいたユーザーガイドの一般化された構造をここに示します。 一般的な方法論は、 この記事に記載されています 。