こんにちは、ハブル！ 私の名前は Lesha です。Alfa-Bank の製品チームのシステム アナリストです。 現在、私は法人と個人起業家向けの新しいオンライン銀行を開発しています。
そして、あなたがアナリストである場合、特にそのようなチャネルでは、ドキュメントがなければどこにも行けず、ドキュメントを使って綿密に作業することはできません。 そして、ドキュメントは常に多くの疑問を引き起こすものです。 Web アプリケーションについて説明されていないのはなぜですか? 仕様ではサービスがどのように機能するかを示しているのに、まったくそのように機能しないのはなぜですか? なぜ仕様書を書いた人のうち XNUMX 人だけが XNUMX 人しか仕様を理解できないのでしょうか?
ただし、明らかな理由から文書を無視することはできません。 そして、作業を楽にするために、ドキュメントの品質を評価することにしました。 私たちがこれをどのように正確に行ったのか、そしてどのような結論に達したかはカットの下にあります。
ドキュメントの品質
本文中で「新インターネット銀行」を何十回も繰り返さないようにNIBと書きます。 現在、私たちは十数のチームが起業家や法人向けの NIB の開発に取り組んでいます。 さらに、それらはそれぞれ、新しいサービスまたは Web アプリケーション用の独自のドキュメントを最初から作成するか、現在のドキュメントに変更を加えます。 このアプローチでは、原則としてドキュメントの品質を高めることができますか?
ドキュメントの品質を判断するために、私たちは XNUMX つの主な特徴を特定しました。
- それは完全でなければなりません。 これはかなりキャプテンらしく聞こえますが、注意することが重要です。 実装されたソリューションのすべての要素を詳細に説明する必要があります。
- 現在のものである必要があります。 つまり、ソリューション自体の現在の実装に対応します。
- それは理解できるはずです。 これを使用する人が、ソリューションがどのように実装されるかを正確に理解できるようにします。
要約すると、完全で最新のわかりやすいドキュメントです。
Опрос
文書の品質を評価するために、私たちは文書を直接扱う人々、つまりNIBのアナリストにインタビューすることにしました。 回答者は、「10 から 1 のスケールで (まったく同意しない - 完全に同意する)」というスキームに従って 5 個の発言を評価するように求められました。
この声明は、定性的文書の特性と NIB 文書に関する調査作成者の意見を反映しています。
- NIB アプリケーションのドキュメントは最新であり、その実装と完全に一致しています。
- NIB アプリケーションの実装は完全に文書化されています。
- NIB アプリケーションのドキュメントは、機能をサポートする場合にのみ必要です。
- NIB アプリケーションのドキュメントは、機能サポートを申請した時点で最新のものです。
- NIB アプリケーション開発者はドキュメントを使用して、何を実装する必要があるかを理解します。
- NIB アプリケーションがどのように実装されているかを理解するために、十分なドキュメントが用意されています。
- NIB プロジェクトが (私のチームによって) 完成した場合、私はすぐにドキュメントを更新します。
- NIB アプリケーション開発者はドキュメントを確認します。
- 私はNIBプロジェクトのドキュメントを準備する方法を明確に理解しています。
- NIB プロジェクトのドキュメントをいつ作成/更新するかを理解しています。
「1 から 5 まで」と答えるだけでは必要な詳細が明らかにならないことは明らかなので、各項目についてコメントを残すことができます。
私たちはこれらすべてを企業の Slack を通じて行いました。システム アナリストにアンケートを取るよう招待状を送信しただけです。 アナリストは15名（モスクワから9名、サンクトペテルブルクから6名）いた。 調査が完了した後、10 個のステートメントのそれぞれについて平均スコアを生成し、それを標準化しました。
それはそれが何であるかわかった。
この調査では、アナリストは NIB アプリケーションの実装が完全に文書化されていると信じる傾向があるものの、明確な同意を与えていないことが示されました (0.2)。 具体的な例として、既存のソリューションの多くのデータベースとキューがドキュメントでカバーされていないことを指摘しました。 開発者は、すべてが文書化されているわけではないことをアナリストに伝えることができます。 しかし、開発者がドキュメントをレビューするという論文も明確な支持を得られませんでした (0.33)。 つまり、実装されたソリューションの説明が不完全になるリスクが残ります。
関連性はより簡単です。ここでも明確な一致はありませんが (0,13)、アナリストは依然として文書が関連していると考える傾向があります。 コメントにより、関連性に関する問題は中間よりも前部に発生することが多いことがわかりました。 しかし、彼らは私たちに支援について何も書いてくれませんでした。
アナリスト自身がいつ文書を作成し更新する必要があるかを理解しているかどうかに関しては、合意はその設計 (1,33) も含めてはるかに統一的でした (1.07)。 ここで不都合として指摘されたのは、文書を維持するための統一ルールが欠如していることです。 したがって、「誰が森に行き、誰が薪を手に入れるのか」モードにならないように、既存の文書の例に基づいて作業する必要があります。 したがって、文書管理の標準を作成し、その部分のテンプレートを開発することが有益な要望となります。
NIB アプリケーションのドキュメントは、機能サポート (0.73) の提出時点で最新のものです。 機能サポートのためにプロジェクトを提出する基準の 0.67 つは最新のドキュメントであるため、これは当然のことです。 実装 (XNUMX) を理解するだけでも十分ですが、疑問が残る場合もあります。
しかし、回答者が（全く満場一致で）同意しなかったのは、NIB アプリケーションのドキュメントは原則として機能サポートのためにのみ必要であるということでした (-1.53)。 アナリストはドキュメントの消費者として最も頻繁に言及されました。 チームの残りのメンバー (開発者) - それほど頻繁ではありません。 さらに、アナリストは、全員一致ではありませんが (-0.06)、開発者は実装する必要があるものを理解するためにドキュメントを使用していないと考えています。 ちなみに、これは、コード開発とドキュメント作成が並行して進行する状況でも予想されます。
肝心なことは何ですか?なぜこれらの数字が必要なのでしょうか?
ドキュメントの品質を向上させるために、次のことを行うことにしました。
- 開発者に書面によるドキュメントをレビューするよう依頼してください。
- 可能であれば、ドキュメントをタイムリーに、最初から更新してください。
- 誰もがどのシステム要素をどのように正確に記述すべきかをすぐに理解できるように、NIB プロジェクトを文書化するための標準を作成して採用します。 さて、適切なテンプレートを開発します。
これらすべてが、ドキュメントの品質を新たなレベルに引き上げるのに役立つはずです。
少なくとも私はそう願っています。
出所： habr.com