業界のドキュメントに対する嫌悪感とは何ですか？
最も基本的なドキュメントを書くことさえ嫌いなようです。私たちのプロジェクトのREADMEは比較的単純です。ドキュメントには依存関係の更新されたリストすらありません。
プログラマーがドキュメントを書くことを嫌う業界で知らないものはありますか？必要に応じてドキュメントの段落を入力できますが、なぜ他の人はそれほど嫌いなのですか？
さらに重要なことに、ドキュメントを書くことで将来的に時間とフラストレーションを節約できることをどのように彼らに納得させることができますか？
自分が良い習慣だと思っていることを採用していない人や、悪い習慣だと思っていることを続けている人の動機を推測することは役に立たないと思います。このビジネスでは、これらのカテゴリのいずれかまたは両方に該当する人は、far目に見える人よりも数が多くなります。自分を狂わせるのはやめてください。
代わりに、問題と可能な解決策に焦点を当ててください。
1。良いドキュメントを自分で書く
あなたのチームの全員があなたが問題だと思うものに努力を向けることを期待するのは現実的ではないかもしれません。これは、あなたがチームの比較的初心者である場合に特に当てはまります。もしあなたがチームの創設メンバーだったなら、あなたはすでにこの問題を早い段階で解決している可能性が高いので、私はあなたがそうだと思います。
代わりに、自分で良いドキュメントを書いて、人々にそれを使ってもらうという目標に向けて取り組むことを検討してください。たとえば、私のチームの誰かがプロジェクトAのソースコードの場所やプロジェクトAに必要な特別な構成を尋ねた場合は、プロジェクトAのWikiページを紹介します。
ファクトリーFの新しい実装を記述してクライアントC用にカスタマイズする方法を尋ねられた場合、開発者ガイドの10ページにあると伝えます。
ほとんどの開発者は、ドキュメントを読むのが嫌いなだけでなく、単に「コードを読む」ことができないように見えるような質問をするのが嫌いです。そのため、この性質の十分な返信が得られたら、まずドキュメントに移動します。
2。ドキュメントの価値を証明
ドキュメンテーションがその価値を証明している（または使用されている場合はそうなるであろう）箇所を指摘するために、あらゆる機会を必ず確保してください。 「私はあなたにそう言った」と控えめにして避けますが、次のようなことを言うのは完全に合法です。
将来の参考のために、このプロジェクトのwikiページには、リリース2.1の継続的なサポートのために作成されたコアコードのブランチに関する情報が含まれているため、将来、リリースされたバージョンを維持している人がチェックする場合、完全な回帰テストを行う必要がなくなりますコードをチェックアウトする前のwiki。
または
タスクTを実行するための手順を書き留めてよかったです。他に誰もそれを使用していないかどうかは本当に気になりません。これにより、自分が書いた時間よりも多くの時間を節約できました。
。ボード上の管理を取得
ドキュメントを作成することで時間とお金を節約できると思われるいくつかのインシデントの後、ドキュメントへの明確な「解凍」に気付くでしょう。これは、見積りにドキュメントの時間を含めることから始めて、要点を押すときです（正直に言って、私は通常、コンパイルやチェックインなどの長いプロセスの実行中にドキュメントを更新/作成します）。特にこれが最近の採用である場合、これは疑問視されない可能性がありますが、代わりに、以前の職場（おそらくそうかもしれません）から取り入れている新しいプラクティスと見なされます。
注意：ほとんどのボスはmakeを好きではありません。特に、課金対象のタスクに直接関連付けられていないものは何もしないので、このサポートは期待していません委任状である。その代わり、より多くのドキュメントを書くための比較的自由な手綱を与える可能性が高くなります。
4。見たときにドキュメントを奨励する
おそらく、人々が必要以上にドキュメントを書かない理由の1つは、誰もそれを読んでいないと感じていることです。ですから、気に入ったものが見つかったら、少なくともそれが利用できてよかったと必ず言ってください。
チームがコードレビューを行う場合は、微妙なWordを2、3回入力して、適切なコメントを促すことができます。
フレームワークGのバグBの回避策を文書化していただき、ありがとうございます。そのことについては知りませんでした。それがなければ、あなたが何をしていたのか理解できなかったでしょう。
ドキュメントについて実際に熱狂的である誰かがチームにいる場合、ランチやコーヒーに行ってその人を育成することは問題ありません。チームの他のメンバーがドキュメントをそれほど重視していないのを見て彼らが落胆するのを防ぐために、少し検証を提供します。
それを超えて、あなたがリードまたは管理職にない限り、それは本当にあなたの問題ではありません。馬を水に導くことはできますが、飲むことはできません。それがあなたの馬でないならば、あなたはそれがのどが渇いていることに満足していないかもしれません、しかしあなたにできることはトラフを満たすことです。
私の経験には2つの主な要因があります。
締め切り
ほとんどの企業は日付に追従しているため、QA、技術的負債、および実際の設計が削減され、プロジェクトマネージャーが見栄えが悪くなったり、ばかげた過剰に約束されたクライアントの期限を迎えたりすることがなくなります。機能的な品質さえ低下しているこの環境では、ドキュメントのような長期的な投資はほとんどチャンスがありません。
変更
開発者にとって比較的新しいベストプラクティスは、コメントの重要度を下げることです。アイデアは、情報を2か所（コード（テストを含む）とコード周辺のコメント）に保持することで、ほとんどのメリットを得るためにそれらを同期させるのに多くのオーバーヘッドが発生するということです。 「コードが読みにくく、コメントが必要な場合は、コードのクリーンアップに時間をかけた方がいいのではないでしょうか？」
個人的にはコメントさえ見ない。コードは嘘をつかない。
ドキュメンテーションも同じ流れに従います。アジャイルの普及により、人々は要件が定期的に変化することを認めています。リファクタリングが広く使用されるようになると、コードの編成は大幅に変化します。変更する必要があるこれらすべてのものを文書化するのになぜ時間を費やすのですか？コードとテストはそれを行うのに十分な仕事をするはずです。
ここには多くの要素が関係しています：
適切に作成されたコードは、独自のドキュメントです。他のすべてが同じである場合、より多くのドキュメントを作成するよりも、それ自体を表すより明確なコードを記述する方が良いです。そうすれば、そのコードを変更するときに、修正するドキュメントが少なくなります。
ドキュメントを書くことは、間違いなくコードを書くこととは異なるスキルです。一部のソフトウェア開発者は他のソフトウェア開発者よりも優れています。ドキュメントを書くよりも、コードを書くのが得意な人もいます。
ドキュメントはonceで書く必要があります。2回ではありません（ソースコードで1回、プログラマガイドでもう一度）。そのため、XMLコメントやドキュメントジェネレータなどがあります。残念ながら、そのようなツールを使用することは、手動でドキュメントを作成することよりも扱いにくく、面倒な場合があります。そのため、これらのツールが広く使用されているとは考えられません。
優れたドキュメントは時間がかかり、うまく処理するのが困難です。他のすべてが同じである場合、既存のコードのドキュメントを作成するよりも、新しいコードを作成する方が価値がある場合があります。
コードが変更されたら、ドキュメントも変更する必要があります。ドキュメントが少ないほど、変更する必要のあるドキュメントが少なくなります。
とにかく誰もドキュメントを読んでいないので、なぜわざわざ？
部屋の象：プログラマーは（必ずしも）ライターではありません。また、実装をテクニカルライターに具体化する必要もありません。部屋の2番目の象：テクニカルライターは、将来の開発者に役立つ詳細を具体的に具体的に説明することはできません（開発者が説明するようにしても）。
複雑なシステムは、適切な文書化がなければ、時間の経過とともに不可解になる可能性があります。コードはそのスタブラビリティに反比例して価値が低くなります[原文のまま]。解決済みの管理者は、開発者からコードと同軸の詳細を読み取ることができるソフトウェアエンジニアを雇い、開発者料金で彼に支払い、文書化と文書化の維持を義務付けます。このライターはコードを読み取ることができ、どのような質問をするべきかを知り、必要に応じて詳細を記入します。 QA部門と同じように、社内のドキュメント部門があります。
サードパーティにライセンスを付与できるため（コードを理解できるため）、コードはより価値が高くなり、コードの監査と改善/リファクタリングがより簡単になり、簡単にできる場所でもコードを再利用できるようになりますソフトウェアのより軽量なバージョンを考慮に入れると、プロジェクトに新しい開発者をより簡単に紹介できるようになり、サポートエンジニアはあなたのために働くのが大好きになります。
これは決して起こりません。
さらに重要なのは、ドキュメントを作成することで将来的に時間とフラストレーションを節約できることをどのように説得できるでしょうか。
それはそれをしますか？
ドキュメントには2つのタイプがあります。
便利なドキュメント
最終製品の使用方法、API、サーバーのIPアドレスやURL名などを文書化します。基本的に、日常的に頻繁に使用されるすべてのもの。間違った情報はすぐに発見され、修正されます。簡単かつ簡単に編集できるようにする必要があります（オンラインWikiなど）。
役に立たないドキュメント
ドキュメントは頻繁に変更されますが、それに興味を持つ人はほとんどいませんし、どこにあるか誰も知りません。実装されている機能の現在の状態のように。または、3年前に更新された、SVNのどこかに隠されているWordドキュメントの要件ドキュメント。このドキュメントは、書くのに時間がかかり、後でそれが間違っていることを見つけるのにも時間がかかります。このタイプのドキュメントに依存することはできません。だめです。時間を無駄にします。
プログラマーは役に立たないドキュメントを書いたり読んだりするのを好まない。しかし、あなたが彼らに役立つドキュメンテーションを示すことができれば、彼らはそれを書きます。私たちが最後のプロジェクトで成功したのは、必要なすべての情報を頻繁に書き込むことができるWikiを導入したときです。
主な理由は意志の欠如とドキュメンテーションの機能の理解の欠如です。考慮すべきドキュメントのクラスがいくつかあります。
製品/リリースドキュメント
これはあなたの「完成した」製品で出て行くものです。これは単なるマニュアルではなく、README、変更ログ、HOW-TOなどです。理論的には、これらを記述しなくても問題はありませんが、ユーザーが使用したくない製品、または不必要に高価なサポート負担になってしまいます。
APIドキュメント
これは、静的に相対的にすべきものを記述します。多数のコンシューマがAPIにコーディングしている可能性があるため、APIの使用方法を説明する文章が価値を持つほど十分に安定している必要があります。サポートされているパラメーター、戻り値、スローされる可能性のあるエラーについて説明すると、他のユーザーが適切な抽象化レベルでAPIを理解できるようになります-インターフェース（not実装）。
コードコメント
現在のところ、コメントに関する業界の意見は流動的であるようです。私が初めてプロとしてコーディングを始めたとき、コードの記述に関してコメントはsine qua nonでした。さて、ファッションはとても明確でコメントが不要なコードを書くことです。これは、一部には、多くの現代言語がはるかに高いレベルで記述されており、Java、JavaScript、Rubyなどで読みやすいコードをアセンブラよりもはるかに簡単に書くことができるためだと思います。 、C、FORTRANなど。したがって、コメントの方がはるかに大きな価値がありました。
コードのセクションの意図を説明するコメント、または特定のアルゴリズムがより多く選択された理由についての詳細のいくつかはまだ価値があると私は信じています明白なもの（実際に修正する必要のないコードを「修正」することによる熱狂的なリファクタリング悪魔を避けるため）。
残念ながら、プログラマーが文書化しないという決定には、多くの利己主義、合理化、および自己妄想があります。コードのように、ドキュメントの主な対象は他の人です。したがって、ドキュメントを作成する（または作成しない）決定は、どのレベルでも、チームレベルで行う必要があります。抽象化のレベルが高い場合は、開発者以外の誰かがそれを実行するほうが理にかなっている可能性があります。コメントレベルのドキュメントに関しては、コメントの目的と意図について合意に達することは、特に能力と経験の混合チームでは、一緒に合意する必要があります。上級開発者が、後輩開発者が近づけないコードを書くのは良くありません。適切に配置され、適切に記述されたドキュメントにより、チームははるかに効率的に運用できます
これが私の2セントです。
アジャイルマニフェストは「包括的なドキュメントを介して動作するソフトウェア」と述べており、誰もがに到達するために読んでいるわけではありません右側の項目に価値があります。左側の項目をさらに評価します。」
悲しいことに、それは https://en.wikipedia.org/wiki/Code_and_fix に一般的であり、ドキュメントはこのモデルでは機能しません（同期しなくなります）。
ソフトウェア開発業界はよく規制されていません。文書を作成するための法的要件はありません。
自己文書化コードが現在の傾向です。
そうは言っても、良いドキュメントはたくさんあると思います。
コードを読むと、howが機能していることがわかります。説明できない理由：コメントが必要です。
コードを読むと、メソッドの名前とパラメータのタイプがわかります。セマンティクスや作者の正確な意図を説明することはできません。コメントが必要です。
コメントはコードの読み取りに代わるものではなく、コードに追加されます。
ドキュメンテーションには時間がかかり、多くの開発者が無用よりも悪いドキュメンテーションを実行しすぎていると思います。ドキュメント化すると、マネージャー（スケジュールのQA部分を削減し続けるのと同じ人）から問題が発生するだけでなく、彼らを含む誰も助けにはならないと考えています。
ドキュメントの半端な部分は、将来への投資です。将来について気にしない場合（次の給料を超えて考えないため、または問題にならないと考えているため）、ドキュメントを作成することは非常に困難です。
他の応答の多くは、少なくとも2種類のドキュメントがあるという点を覆い隠しています。1つは他の開発者向けのセット、もう1つはエンドユーザー向けのセットです。環境によっては、システム管理者、インストーラー、ヘルプデスク担当者向けの追加のドキュメントも必要になる場合があります。各対象者は、異なるニーズと理解のレベルを持っています。
（ステレオ）典型的な開発者を考えてみてください：彼は選択的にコーダーです。彼は世間の目からキャリアを選び、主に彼自身と通信するキーボードの後ろで長い時間を費やしています。ドキュメンテーションのプロセスはcommunicationの形式であり、優れたドキュメンテーションを生成するために必要なスキルセットは、優れたコードを生成するために必要なスキルとは正反対です。
優れたドキュメント作成者は、ユーザーの言語、管理の言語、サポートスタッフの言語、開発者の言語など、複数の言語でコミュニケーションできます。ドキュメント作成者の仕事は、コーダーが伝えていることを理解し、それを他のすべてのグループが理解できる形式に変換することです。
コーダーが優れたコミュニケーターになるために必要なスキルを開発することを期待している場合（書面またはその他）、主要なスキルセット（コーディング！）を磨くために費やされる時間が削減されます。彼が自分の快適ゾーン（コーディングおよび他のコーダーとの通信）から離れるほど、タスクを適切に実行するためにより多くの時間とエネルギーが必要になります。あなたはプロのコーダーが他のすべてを犠牲にして、主に彼のコアコンピテンシーに集中することを望むことを合理的に期待できます。
このため、ドキュメント（インラインコードコメントを除く）は、プログラマではなくコミュニケータに任せるのが最善です。
ドキュメントはコードのように実行されません。その結果、ドキュメントが適切で完全であることを確認するための効果的なフィードバックループがないことがよくあります。これは、コードのコメントが腐敗する傾向があるのと同じ理由です。
Donald Knuthは、ソフトウェアの品質を向上させる方法として 文芸的プログラミング を促進し、コードを使用してドキュメントを効率的に作成しました。このアプローチを非常に効果的に使用したいくつかのプロジェクトを見てきました。
個人的には、コードのパブリックAPIを可能な限り読みやすくするという現代の傾向に固執し、ユニットテストを使用して他の開発者の使用法を文書化しようとします。これは、APIを調査および発見できる形式にするという大きなアイデアの一部だと思います。このアプローチは [〜＃〜] hateoas [〜＃〜] がWebサービスで実現しようとしていることの一部だと思います。
マイナーなポイントですが、不愉快なほど少ないドキュメントを書く開発者にとっては重要と思われるポイントです。つまり、タイプできないのです。 10指システムの近似値がある場合、それが簡単だからといって、より多くのドキュメントを書く傾向があります。しかし、あなたが狩猟とつつきに行き詰まっている場合、あなたは失われます。私が採用を担当するのであれば、これは実際に確認したいことです。
ドキュメントを読むことを嫌う人は、ドキュメントを書くことを嫌います。多くのプログラマーは、ドキュメントを完全に読まないようにできる限りのことをします。
書くことに集中するのではなく、読むことに集中してください。プログラマーがドキュメンテーションを読んでそこから物事を同化するとき、彼らはその価値を見、いくつかを書く傾向がはるかに強くなります。