チームがダイアグラムを作成するのをそれほど怖くないようにするにはどうすればよいですか？
環境
私は、ドキュメント内の明確で説明的な図の強力な支持者です。それらが適切に行われると、2つの側面が大幅に向上します2つの側面：ドキュメントの理解と、開発者がすでに読んだものを思い出す必要があるときにドキュメントを読むのに費やす時間。
私が見つけた唯一のツール（1）オンライン（インストールするものなし）、（2）使いやすい、（3）特定の制約を課さない（UMLツールとは対照的）、（4）ベクトルを埋め込むことができる今後の編集用のPNG画像内の情報は draw.io です。他のオンライン描画ツールと同様に実用的ですが、ドキュメントに埋め込まれた図の特定の使用法には1つの大きな欠点があります。図が作成されると、それを変更するために追加の手順が必要になります。 Markdownファイル。
問題は、遅かれ早かれ、状況が変化することです。たとえば、Arduinoデバイスと通信するために私が開発したプロトコルの一部を示す次の図を見てください。
複数の点が変わる可能性があります。
- CRCはもう必要ないと思うかもしれません。または、そのCRCは代わりに16ビットを取る必要があります。
- または、魔法の2ビット値
0b10丈が急に変わる前に0b11。 - または、2行目の「エリア」を「カテゴリ」に名前変更できます。
- または、レベルブロックとエリアブロックの前にラインブロックを配置することもできます。
次に別の例を示します。
ここでは、次のことを行います。
- 抵抗器を交換し、
- ピンを交換し、
- コンポーネントの追加または削除、
- LEDの色を変更します。
これらの変更のいずれかを実行する場合、私には選択肢があります。
- PNGをダウンロードして、draw.ioに移動し、PNGをインポートして編集し、エクスポートして、所属するディレクトリに移動して、変更をコミットします。これには数分かかる場合があります。
- または、図を古くしておくと、数年後の古いプロジェクトの図を信頼できなくなります。
- または、図を取り除き、後で画像をちらっと見るのではなく、テキストによる説明を読む必要があります。
問題
チームで作業しているとき、図が2つの問題を引き起こすことに常に気づきます。
一部の人々は、それらを変更するのが難しすぎると感じ、古くなっても気にしない。
一部の人々は、図が古くなるのではないかと懸念しているため、別の戦略を選択しました。コードと図を異なるものにする変更やリファクタリングを避けることです。基本的に、最初の図に対応するプロジェクトで「エリア」の名前を「カテゴリ」に変更することが理にかなっている場合、変更は複雑すぎるため、「エリア」という用語をそのまま使用します。または、16ビットCRCに切り替えるのが理にかなっている場合は、8ビットCRCを維持する理由を考案します。
私はそれらの人々を完全に理解しており、時々まったく同じことをします。
質問
私の質問は、含まれているものを変更することを恐れずに、プロジェクトを最新の優れた図にすることを奨励するために、技術的または人間レベルでこれらの状況を防止または少なくとも軽減するために何ができるかです図では？
私が探している答えは次のようなものです。「これか、それを使って、構成ファイルに基づいてその場でダイアグラムを魔法のように生成できます...」または「これをやって、人々に信じさせることができます。図の更新は簡単であり、日々の作業の一部である必要があります...」または「図を解析してソースコードと照合し、古くなっている場合にビルドを失敗させることができます...」
これには、2つのアプローチが必要です。Ewanが提案する自動化ツールと、作業範囲の一部としてこれらの図の更新を含めることです。
自動化されたツールは、ぶら下がっている果物を捕まえますが、複雑さのため、または高度にカスタマイズされたフォーマットが必要なためにプログラムで生成できない図があります。さらに、まだ存在しないコードまたはハードウェアに基づいて図を生成することはできません。
自分がこれに毎日遭遇する度合いははるかに低いです。私たちの図は、UMLクラス図とシーケンス図になる傾向があります。コードからクラス図を生成するツールは存在しますが、まだ記述されていないコードに対してはあまり機能しません。さらに、キュレーションされたクラスのサブセットのみを含むUML図を理解するのが簡単になります。これらの図の更新には時間がかかり、これは作業に追加されますが、チームは一方的にそれらの値を確認します。そのため、私たちのチームは、この情報を維持するための追加の時間を考慮して、物事をはるかに小さなチャンクに分割します。これはアジャイルプロジェクトであるため、ストーリーポイントごとの機能単位が少なくなり、機能を完了するためのストーリー数が多くなります。
作業量を見積もる前に、開発者は少し調査をして、どの図を更新する必要があるかを大まかに特定する必要があります。その後、これはスプリント計画のタスクになり、通常は開発者のタスクをブロックします。
8ビットCRCから16ビットCRCに移行するためのダイアグラムの更新は、他のタスクと基本的に同じように処理する必要があります。あなたはそれを計画し、それが依存しているものとそれがブロックしているものを特定する必要があります。その後、チームは、エンジニアリングプロセスの通常の一部としてドキュメントを更新するという期待を理解します。彼らは事前にこの作品を特定しているので、それはそのようなショックとして来ることはなく、それは何か特別なもののように見えることもありません。これは、機能を実現するプロセスの自然なステップになります。
同様の機能の見積もりが増え始めても驚かないでください。これを受け入れます。それと戦うな。明確に定義されたタスクを用意することで、増加した見積もりを管理者に正当化できます。見積もりの増加により、チームはこれらのスキルを学び、熟練する時間を確保できます。時間が経つにつれ、チームがより多くの練習を行ったというだけの理由で、ユーザー向けの機能の数が実際に戻ってくるのを目にすることがあります。前回のスプリントのように、このような出力の増加を経験しましたが、あなたの質問とは無関係な種類のタスクのために。
数か月間、私たちはチームがほぼ4年間取り組んできた自動テストに大きな重点を置いていました。私はチームと協力してストーリーを細かく分割し、開発タスクではなくストーリーであるとはほとんど信じられませんでした。 2〜3階建てだった可能性のある機能は、6から10階建てで3倍、4倍の合計ストーリーポイントになりました。前回のリリースはかなり悲惨でしたが、チームは多くのことを学びました。スプリントあたりのストーリーポイントはこの期間で変化しませんでした。達成した機能は少なくなりました。
突然、警告なしに、我々は最後のスプリントを打ち砕き、チームは彼らの速度を2倍以上にした。プロセスの一部として、これらの3か月のスローダウンの正規化された自動テストが判明し、チームは本当に大きな前進を遂げました。自動化されたテストを書くのに戦った人はいません。それがルーティンの一部になり、それが鍵となります。チームに新しいものをルーチンに組み込むための予備のサイクルを与えます。 習慣を形成する時間を与えてください。
人々はより多くの練習をしてきたので、私は今、ストーリーポイントの見積もりが戻ってきているのを見ています。いくつかの開発作業を行って1つのテストを書くことは8ポイントだったかもしれませんが、今ではこれが3および5ポイントに低下しているのがわかります。プロセスの一部としてダイアグラムの更新を導入すると、同様のパターンが表示されます。
つまり、すべては次のようになります。
- 機能を停止します—停止します。
- 作業を見積もる前に更新が必要な図を調査する
- 他の開発関連タスクと同様に、ドキュメントの更新を計画する
- 見積もり単位あたりの機能の低下を受け入れる（または機能あたりの見積もりの全体的な増加）
- そして人々に練習する機会を与えなさい。
プログラムでダイアグラムを生成するツールを使用することをお勧めします。
たとえば、グラフのDOT構文 https://www.graphviz.org/doc/info/lang.html
またはneo4j視覚化
私はあなたが電気回路図のために何かを見つけることができると確信しています、よりカスタムなもののためにあなたは何かを書かなければならないかもしれません。しかし、htmlドキュメントの場合、これは一部の埋め込みJavaScriptになる可能性があります。
これは、最初は少し大変な作業であることを意味しますが、将来の編集者は、何も描画しなくても、ダイアグラムの基本的なプロパティを簡単に変更できます