📝

ドキュメントの種類と意味

2021/12/11に公開約2,100字

ドキュメントには3つのモードが存在する

UMLモデリングのエッセンス という本にドキュメントのモードが書かれてある。

  • スケッチ
  • 設計図面(blueprint)
  • プログラミング言語

ここでいうところのプログラミング言語とは、成果物としてのドキュメントでそれ自体をつくることを目的とする。プログラミング以外の文脈では、実際のポスターや法的な契約書などと読み替えてほしい。

用語説明

フォワードエンジニアリング

これから新しくものを作る

リバースエンジニアリング

既存のものを理解する

スケッチ

簡易的なドキュメント。文書でもいいがホワイトボードとかが便利。完全性よりも伝達性が重視される。文書や図面の規格や規則はない。

フォワードエンジニアリングにおけるスケッチ。

スケッチの本質は選択可能性にあります。フォワードスケッチ(物事を行う前のスケッチ)を使用すると、記述するコードについてチームのメンバーと話し合い、問題への対応方法を計画することができます。スケッチを使用する目的は、これから行うことに関するアイディアや選択肢を他の人に伝えることです。記述するすべてのコードについて説明するのではなく、前提条件としてメンバーに把握してほしいことや、プログラミングを始める前に視覚化しておきたい部分だけを節目いすることができます。このような打ち合わせはごく短時間ですみます。数時間のプログラミングの打ち合わせならば10分、2週間の反復型開発の打ち合わせならば1日で行うことができます。

リバースエンジニアリングにおけるスケッチ。

リバースエンジニアリングでは、スケッチを使ってシステムの特定の仕組みを説明します。すべてのクラスを説明する必要はなく、コードの記述を始める前の話題として興味を引き、取り上げるのにふさわしいものを説明するだけでかまいません。

設計図面

完全性を重視する。設計者と実装者が別で、かつその間の対話の心理的物理的ハードルが高い場合に選択される(もしくはコストの観点)。

フォワードエンジニアリングにおける設計図面。

フォワードエンジニアリングでは設計者が設計図面を作成しますが、その役割はプログラマがコードを作成するための詳細な設計を行うことです。この設計は、設計に関するすべての意思決定が明確になるだけの完成度を必要とし、プログラマとしては悩むことなく極めて直接的に従うことができる支持になっていなければいけません。設計者とプログラマが同一人物である場合もありますが、多くの場合、設計者はプログラマチーム向けに設計をおこなう上級開発者です。このアプローチの発送のもとになっているのは、技術の専門家が設計図面を作成して建設会社に渡し、建設会社が建築をするというような、他分野におけるエンジニアリング形態です。

リバースエンジニアリングにおける設計図面。

リバースエンジニアリングにおける設計図面の目的は、紙の文書で、またはインタラクティブなグラフィックブラウザで、コードの詳細情報を伝えることです。設計図面では、開発者が理解しやすいようにクラスの詳細をすべてグラフィカルに示すことができます。
設計図はタスクで必要とされる詳細を扱うため、スケッチよりも洗練されたツールが必要です。専門分野に特化したCASE(Computer Aided Software Engineering)ツールはこのカテゴリに入りますが、CASEという用語が好まれなくなってきたため、現在ベンダーはこの言葉を使わないようにしています。フォワードエンジニアリングツールはダイアグラムの描画をサポートし、情報を保存するためにリポジトリに格納します。リバースエンジニアリングツールはソースコードを読み取り、ソースコードを解釈してリポジトリに入れ、ダイアグラムを生成します。

スケッチと設計図面の違い

境界はやや曖昧だが、スケッチは故意に不完全にして重要な情報を強調するものに対して、設計図面は包括的であることを意図し、多くの場合は直接プログラミングを単純でかなり機械的なアクティビティにすることを目的としている。標語風にいえば、スケッチは探索的であり、設計図面は確定的である。

以上を踏まえてどのようなドキュメントを残したいか

アジャイル的な開発としてつぎの2つの目的をもつドキュメントを残すことを提案したい

  • 現在のスケッチ置き場
  • オンボーディング資料置き場

これは古くなったスケッチはオンボーディングにおけるノイズになりうるので、どんどんアーカイブさせていくという意味。

Discussion

ログインするとコメントできます