適切な量​​のドキュメントを決定する

私が現在取り組んでいる一般的なアプローチは-

ドキュメントをできるだけ避けます

別のチームが必要とする場合のみ文書化する

明確にするために、私はコードドキュメントを意味するのではなく、これは私たちが行うことです。つまり、UMLまたはDBスキーマ、クラス図、仕様などのワードドキュメントの場合、設計プロセスを取り巻くすべてのドキュメントを意味します。

文書化しない上司の理由を挙げます。

1. 時間がかかります-実装に集中してください
2. 設計が変更された場合-ドキュメントは変更され、二重の問題が発生します
3. 結局、誰も読みたくない何百ものページを取得し、誰も実際には編集しないので、いつかは古くなるでしょう
4. その痛み-誰も本当にそれをしたくない

今では作業が速くなることに気づきましたが、何も理解せずに、ここに行って古いコードに直接飛び込んだ時間も覚えています。

実際、私はまだこの古いコードのほとんどを取得していません。場合によっては、さまざまな開発者からの多くのパッチが小さな調整を試みているのを目にすることがあります。

ドキュメント化の欠如は、この種のパッチと広義のシステム理解の欠如を助長すると思います。

私の質問は：

チーム間で継続的な知識を促進しながら、迅速かつ効率的になるように、ドキュメントをどのようにバランスさせることができますか？

私はどの文書もない文書よりも優れていることを発見した。適切な量​​は、通常、それを行う必要がある時間の長さ、またはサポートへの電話と電子メールの嫌悪度によって決まります。

現在のチームメンバーは、記憶について非現実的な期待を持っているか、ライティングスキルを恥じており、練習する気がありません。

私はここに少数派（大学院でソフトウェアエンジニアリングに入学した英語専攻）であることに気づきました。ドキュメンテーションが雑用として見つからないからです。それは貴重な専門的なツールです。同僚のように書くのが難しいとは思わないかもしれませんが、それは主に、練習を積んでいるためです。ドキュメントがない限り、プロジェクトは完了したとは見なしません。通常、純粋に利己的な理由でプロジェクトを作成します。電話やメールを受け取る代わりに、読むものを提供したり、最後に話していたことを思い出したりできます。月、または私はそれが夜中にそれをサポートする必要がある場合私が何かをした方法を参照することができます。

ドキュメントにアプローチする最善の方法は、テストコードを書くのとまったく同じように、好きなように書くことです。いくつかの事前に記述されたテンプレート（ヘッダー、コードのスタブなどを含む）を使用すると、ドキュメントを簡単かつ迅速に作成できるのは驚くべきことです。このようにして、変化が起こったときにそれを捉えることができ、時間をかけてカバーする余地が少なくなります。必要に応じてドキュメントを参照し、途中で変更できるため、この方法の方が効率的です。たとえば、ウィキでこれを行うと、更新が容易になります。最新かつ最高のものが常に同じ場所でオンラインになっている場合は、ドキュメントのバージョンの問題を回避でき、読む必要がある人にリンクを送信できます。

文書化に少し時間を費やすと、特に誰かが新しいチームに加わったときに、すべての作業に時間を費やす必要がないため、作業が速くなります。物事を把握することは私たちの仕事の楽しい部分ですが、生産を修正するために急いでそうしなければならないときは、楽しくありません。私たち全員がさらに2、3のメモを書いておけば、多くの時間を節約できます。

あなたのチームはテストやテストコードの記述に関して同じ問題を抱えていますか？そうでない場合、これはより簡単な販売になります。

ドキュメントは多くの点で役に立ちます
。1）プロジェクトに取り組むときに、あなたにとって、今、そしてあなたの同僚にとって。

2）お客様へ。ユーザーに表示できるドキュメント（図を含む）があると、特に複雑なシステムについて話し合う場合に、会議での話し合いが容易になります。ドキュメントが不完全な場合でも、それは出発点です。

3）あなたの仕事を受け継ぐ人たち（3年後にはあなたかもしれません）。若い同僚の多くは、いつまでも物事を覚えていると思います。書き留めない限り、今週は覚えていません。ドキュメントを作成すると、何かをどのように構造化したかを覚えるのに半日を費やす必要がなくなり、すべてをもう一度理解する必要がなくなります。

4）状況が政治的または論争になる場合、あなたと他の人に。会議でメモをとる人として、目を覚まして退屈と戦うために、私は決定書を書いた唯一の人でした。それを書き留めた人が紛争に勝ちます。次回誰かが「この冬、会議室4で会ったことを思い出してください。Xを通過したとき、フレッドがそこにいて、会計のあの人は誰ですか？」

私の最後の数人の雇用主には、「開発」ウィキがありました。重要な機能のチャンク（新しいインポート/エクスポートフィード、セキュリティサブシステムのしくみ、システムがアップロードされたドキュメントをどこに保存するかなど）はすべてそこに文書化されています。通常、コードレビューのステップの前に完了する必要がある項目です。通常、最初は少し抵抗がありますが、誰かが少しの情報を調べに行く必要があり、そこにある場合、別の改宗者がいます。

これをwiki形式で作成することの良い点は、Wordの書式設定などをすべて行う傾向が少なく、保存する必要のある実際の情報を書き出すことです。ほとんど（すべてではない）のwikiパッケージでは、ドキュメントまたは画像（Visio UML図やUIワイヤーフレームなど）をアップロードできるため、視覚的な要素も持つことができます。

ほとんどの場合と同様に、機能する可能性のある最小限の量を実行する必要があります。しかし、それはどれも同じではありません。

適切なドキュメントを作成するための時間の割り当てを逃れることはできません。ただし、与えられた作業量に応じて、必要に応じてバランスを取ってください。ただし、時間の15〜20％を残して、行ったことを文書化してください。マネージャーを含め、チームの全員がこれに参加している必要があります。そうしないと、他の人の利益のために文書化するだけで、何の見返りもありません。ドキュメント化は、開発プロセスの不可欠な部分でなければなりません。

HOWの部分を実際のコードに、WHATの部分を単体テストに任せながら、なぜ何かをしたのかをドキュメントに記載する必要があります。それ以上のものは苦痛です。これは通常、出発点だけを求めるスマートな人には十分です。

また、コードベースの各大きなコンポーネントの全体的な高レベルのアーキテクチャを維持することを忘れないでください。新しいチームメンバーの採用を非常に簡単にします。

最後に、奇抜な修正を追加するときはいつでも、コメントからバグデータベースにリンクしてください-非常に便利です。

上司は、誰も読まないUMLドキュメントを印刷しないでください。私たちのチームでは、クラス図ビューを使用してモデル内をライブでナビゲートしています。原則は、MOFを常に更新することであり、UMLモデルはコードからライブになり、クラス図はモデルのビューアではなく、モデル自体になります。

すべての複雑さがモデルレベルのバックオフィスで行われるため、それは本当にうまく機能します。プロジェクトをリファクタリングしたり、Java docを記述したり、モデルにUMLドキュメントを記述したりできます。それは一種のクリックアンドゴーです。クリックすると、ライブドキュメントが表示されます。何かがはっきりしない場合、私はクラス図を開いて、それで遊んでいきます。図の分類子からの削除、新しい分類子の追加、ズームインとズームアウト、関連付けの表示、関連付けの削除など...新しいモデル情報を作成しないため、モデルは変更されません。使用するだけです。

パッケージの図を開き、クラス図でこのクラスがどうあるべきかについてのコメントを直接読むことができることが非常に重要です。このメソッドが何をすることになっているのか、そしてフローなどは何ですか...

UMLは素晴らしい、本当に役立つが、モデリング/開発段階でより多くの柔軟性と反復を提供するために、モデル駆動型開発の使用を停止する必要があります。クラス図はコードからライブ更新され、ドキュメントは常に正確であり、クリックするだけで利用できます。ツールについては触れませんが、JavaとEclipseを使用している場合は、どのツールを使用しているかを簡単に見つけることができます。