ドキュメントの劣化-対処方法
重要:ソースコードのドキュメントに問題はありません。これは通常のコード監査に属し、最新の状態に保たれます。私たちの問題は、開発者のドキュメント(または、必要に応じて「外部」)、プログラマーからプログラマーへのブログのような小さなヒントです。 ウィキのようなシステムを使用して、プログラマーのドキュメントを作成します。プログラマーのためにプログラマーが書いた記事は、特定のコードがどのように機能するかをもう少し詳しく説明しています。これらのWikiページには通常、次のものが含まれます。 APIの各部分の設計決定の背後にある動機(たとえば、この特定のサードパーティライブラリがこの方法で何かを行うことを望んでいるため、このotherいことをしました。 特定の一般的なタスクを処理する方法の説明(たとえば、適切なアプリケーションスタイルを参照し、レジストリコンポーネントに自分自身を登録し、他のコンポーネントによって自動的に「スキャン」されるために何らかのインターフェースを実装する必要がある些細なポップアップを表示する) 良い習慣(主観的なもの、実際にこのようなものを書き留めます) 環境設定、必要なツールとそのセットアップ 一般に、主にサイズとブログ投稿/記事のような性質のために通常のコード文書に適合しないコードの記述に関連するもの。 問題 このシステムを導入することは数か月前には良い考えのように思えましたが、最近では解決するよりも多くの問題を引き起こしているように感じます。例えば: 人々は記事を書きます...しかし、コードが変更されると、Wikiの更新はめったに続きません 急いで誰かが書いたスクラッチ記事の多くは、そのように残しました 記事のリクエストは通常プロジェクトリーダーからのものですが、正確性や構成についてはほとんど検証されていません。 通常の劣化。コードは変更されましたが、wikiは変わりません。誰かが次に情報を探すとき、彼が通常見つけるのは、時代遅れの低品質のものの束です-そして、何が起こっているのか、彼が見つけたものが正確であるのか、(さらに悪いことに)その一部であるのか疑問に思っています。そして、助けになるはずだったものが、逆になります。 現時点では、プロジェクトリーダーを含め、人々は問題を認識しているようですが、明らかにそれで何かをすることに煩わされる人はいないようです(または、もっと面白いことがあります)。 私の最初の考えは、それをすべて忘却の中に投げ込むことでした(時代遅れの「ヒント」に何回か噛まれた後)。しかし、それは極端すぎるかもしれません。いくつかの情報は注意する価値があり、時々読むことをお勧めしますが、問題は依然として同じです。「最新」にどのように対処しますか?ソースコードに何らかの形でリンクされていますか(したがって、ファイルの更新バージョンがチェックインされると、記事の作成者はコード/記事を修正する必要があるかもしれないと通知されます)?指定された人は、毎日の基本でそれを「見守っていますか」?定期的なクリーンアップを行いますか?