そして、あなたがアナリストである場合、特にそのようなチャンネルでは、ドキュメントやハードワークなしで-どこにもありません。 そして、ドキュメントは常に多くの質問を提起するものです。 Webアプリケーションが記述されていないのはなぜですか？ 仕様がサービスの動作方法を示しているのに、まったく動作しないのはなぜですか？ 仕様を理解できるのは2人だけで、そのうちの1人が仕様を書いたのはなぜですか？
ただし、明白な理由でドキュメントを無視することはできません。 そして、私たちの生活を簡素化するために、ドキュメントの品質を評価することにしました。 正確にこれをどのように行い、どのような結論に達しましたか？
ドキュメントの品質
「New Internet Bank」というテキストを数十回繰り返さないために、NIBを作成します。 現在、私たちは起業家や法人向けにNIBの開発に取り組んでいる12以上のチームを持っています。 さらに、それぞれがゼロから新規サービスまたはWebアプリケーションの独自のドキュメントを作成するか、現在のドキュメントに変更を加えます。 このアプローチでは、ドキュメントは原則として高品質になりますか？
また、ドキュメントの品質を判断するために、3つの主要な特性を特定しました。
- 完全でなければなりません。 かなりキャプテンに聞こえますが、注意することが重要です。 実装されたソリューションのすべての要素を詳細に説明する必要があります。
- 関連する必要があります。 つまり、ソリューション自体の現在の実装に対応します。
- はっきりしているはずです。 それを使用している人がソリューションの実装方法を理解していること。
要約-完全で関連性があり理解しやすい文書。
世論調査
ドキュメントの品質を評価するために、直接作業する人、NIBアナリストにインタビューすることにしました。 回答者は、「1から5のスケールで（完全に同意しない-完全に同意する）」のスキームに従って10のステートメントを評価するように求められました。
申し立ては、品質文書の特性と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.07）を含め、合意はすでにはるかに統一されていました（1.33）。 ここで不便な点として指摘されたのは、ドキュメントを維持するための統一されたルールがないことです。 したがって、「誰が森にいるのか、誰がfireのために」体制を含まないために、彼らは既存の文書の例に基づいて働かなければなりません。 したがって、ドキュメントを維持するための標準を作成し、その部分のテンプレートを開発することは有用な願いです。
NIBアプリケーションのドキュメントは、機能サポート（0.73）の提供時に関連しています。 プロジェクトを機能的にサポートするための基準の1つが最新のドキュメントであるため、理解できます。 実装を理解するだけでも十分です（0.67）が、疑問が残る場合もあります。
しかし、回答者が（むしろ満場一致で）同意しなかったのは、原則として、NIBアプリケーションに関するドキュメントは機能的なサポートにのみ必要であるということです（-1.53）。 ドキュメントの消費者としてのアナリストが最も頻繁に言及されました。 残りのチームメンバー（開発者）-はるかに少ない。 さらに、アナリストは、開発者はドキュメントを使用して実装する必要があるものを理解しないと信じていますが、満場一致ではありません（-0.06）。 ちなみに、これは、コード開発とドキュメントの作成が並行して行われる状況でも予想されます。
結果は何ですか、なぜこれらの数字が必要なのですか
ドキュメントの品質を改善するために、これを行うことにしました。
- 開発者に書面による文書のレビューを依頼してください。
- 可能であれば、ドキュメントをタイムリーに更新します-そもそも。
- NIBプロジェクトを文書化するための標準を作成して採用し、誰もがシステムのどの要素とそれらの記述方法をすぐに理解できるようにします。 さて、適切なテンプレートを開発してください。
これはすべて、ドキュメントの品質を新しいレベルに引き上げるのに役立つはずです。
少なくともそう願っています。