業界のドキュメントに対する嫌悪感は何ですか？

最も基本的なドキュメントでさえも書くことに嫌悪感があるようです。プロジェクトのREADMEは比較的むき出しです。ドキュメントには依存関係の更新されたリストさえありません。

プログラマーがドキュメンテーションを書くことを嫌うような業界で私が知らないことはありますか？必要に応じてドキュメントの段落を入力できますが、なぜ他の人はそれを嫌うのですか？

さらに重要なことは、ドキュメントを書くことで将来の時間とフラストレーションを節約できることを彼らに納得させるにはどうすればよいでしょうか？

良い習慣だと思うものを採用していない人や、悪い習慣と思われることをし続けている人の動機を推測することは役に立たないと思います。このビジネスでは、これらのカテゴリのいずれかまたは両方に分類される人の数は、目と目で見る人よりもはるかに多いため、夢中になるのはやめてください。

代わりに、問題と可能な解決策に焦点を合わせます。

1.適切なドキュメントを自分で作成する

チームの全員が、あなたが問題とみなすものに努力を向けることを期待するのは現実的ではないかもしれません。これは、あなたがチームの比較的新参者である場合に特に当てはまります。あなたがチームの創設メンバーであった場合、あなたはすでにこの問題を早期に解決している可能性が高いので、私はあなたがいると推測しようと思います。

代わりに、良いドキュメントを自分で書き、それを人々に使用してもらうという目標に向かって取り組むことを検討してください。たとえば、プロジェクトAのソースコードがどこにあるのか、プロジェクトAが必要とする特別な構成は何かをチームの誰かから尋ねられたら、プロジェクトAのWikiページを指し示します。

ファクトリーFの新しい実装を作成してクライアントC用にカスタマイズする方法を誰かから聞かれたら、開発者ガイドの10ページにあると伝えます。

ほとんどの開発者は、ドキュメントを読むのが嫌いなだけでなく、「コードを読む」ことができないように見える質問をすることを嫌うので、この種の十分な回答の後、最初にドキュメントに行きます。

2.ドキュメントの価値を証明する

ドキュメントがその価値を証明している（または、使用されている場合は持っている）箇所を指摘するために、あらゆる機会を利用してください。微妙で「そう言った」のは避けましょうが、次のようなことを言うのは完全に合法です

将来の参考のために、このプロジェクトのWikiページには、リリース2.1の継続的なサポートのために作成されたコアコードのブランチに関する情報があるため、リリースされたバージョンを維持している人がコードをチェックアウトする前にウィキ。

または

タスクTを実行するための手順を書き留めてとてもうれしいです。誰もそれを使用したことがないかどうかはあまり気にしません。

3.ボード上の管理を取得

文書を作成することで時間とお金を節約できることが実証されたいくつかの事件の後、おそらく文書に対する明確な「解凍」に気付くでしょう。これは、ドキュメントの時間を見積もりに含めることからポイントを押す時期です（正直なところ、通常、コンパイルやチェックインなどの長いプロセスの実行中にドキュメントを更新/作成します）。特にこれが最近の採用である場合、これは質問されない可能性がありますが、前の職場から持ち込んでいる新しいプラクティスと見なされる可能性があります（そうかもしれません）。

注意事項：ほとんどのボスは、特に請求可能なタスクに直接結び付けられていないことを中心に、人々に何かをさせることを好まないため、このサポートがマンデートの形式になることを期待しないでください。代わりに、より多くのドキュメントを作成するための比較的自由な手綱を提供する可能性が高くなります。

4.見たときにドキュメントを奨励する

人々がドキュメントを必要な頻度で書かない理由の一部は、誰もそれを読んでいないと感じるからかもしれません。そのため、気に入ったものを見つけたら、少なくとも入手できてよかったと言ってください。

チームがコードレビューを行う場合は、良いコメントを促すために微妙な言葉を1つまたは2つ入力してください。

フレームワークGのバグBの回避策を文書化していただきありがとうございます。それについては知りませんでしたが、それなしではあなたが何をしていたのか理解できなかったと思います。

実際にドキュメンテーションに熱心な人がチームにいる場合、昼食やコーヒーに行くことでその人を養成し、チームの他のメンバーを見ることで得られる落胆を打ち消すための少しの検証を提供することを確認しますドキュメントをそれほど重視していません。

それを超えて、あなたがリードまたは管理職でない限り、それは本当にあなたの問題ではありません。馬を水に導くことはできますが、飲むことはできません。それがあなたの馬ではないなら、のどが渇いていることに不満を感じるかもしれませんが、できることは谷を埋めることだけです。

私の経験には2つの主な要因があります。

締め切り

ほとんどの企業は日付主導型であるため、プロジェクトマネージャーの見た目が悪くなったり、見込みのないクライアントの納期に間に合わないように、QA、技術負債、および実際の設計が削減されます。機能的な品質さえもカットされるこの環境では、ドキュメントのような長期的な投資にはほとんどチャンスがありません。

変化する

開発者にとって比較的新しいベストプラクティスは、コメントを強調しないことです。アイデアは、情報を2つの場所（コード[テストを含む]とコードの周りのコメント）に保持すると、ほとんど利益をもたらさずに情報を同期させるために多くのオーバーヘッドが生じるということです。「コードが読みにくいためコメントが必要な場合は、コードのクリーンアップに時間を費やした方がいいでしょうか？

個人的にはコメントを見ることもありません。コードは嘘をつくことはできません。

ドキュメンテーションも同じ流れに従います。アジャイルの普及により、人々は要件が定期的に変わることを認めています。リファクタリングの普及により、コードの構成は大幅に変わります。なぜ変化しなければならないこのようなものすべてを文書化するのに時間を費やすのですか？コードとテストはそれを行うのに十分な仕事をする必要があります。

ここにはいくつかの要因があります：

1. 適切に記述されたコードは、独自のドキュメントです。他のすべての条件が同じであれば、より多くのドキュメントを作成するよりも、それ自体を表す明確なコードを作成する方が適切です。それを行うと、そのコードを変更するときに、より少ないドキュメントを変更する必要があります。

2. ドキュメントの作成は、おそらくコードの作成とは異なるスキルです。一部のソフトウェア開発者は、他のソフトウェア開発者よりも優れています。ドキュメントを書くよりもコードを書く方がはるかに優れている人もいます。

3. ドキュメントは2 回ではなく、1回だけ記述する必要があります（ソースコードに1回、プログラマガイドに1回）。そのため、XMLコメントやドキュメントジェネレーターなどがあります。残念ながら、そのようなツールを使用することは、単に文書を手書きで書くよりもトリッキーで扱いにくい場合があります。そのため、これらのツールは広く使用されていません。

4. 良いドキュメントは時間がかかり、うまくやるのは難しいです。他のすべての条件が同じであれば、既存のコードのドキュメントを書くよりも新しいコードを書くほうが価値があります。

5. コードが変更されると、ドキュメントも変更する必要があります。ドキュメントが少ないほど、変更する必要は少なくなります。

6. とにかくドキュメントを読む人はいないのに、なぜわざわざ？

部屋の象：プログラマーは（必ずしも）ライターではありません。また、技術ライターに実装を具体化することに必ずしも従う必要はありません。部屋の2番目の象：テクニカルライターは一般に、将来の開発者にとって有用な詳細を具体化することはできません（開発者が彼らに説明することを決めたとしても）。

複雑なシステムは、適切な文書化なしに時間が経つと、不可解に近くなる可能性があります。コードは、その正確性に反比例して価値が低くなります[原文]。解決済みの管理者は、開発者からコードと同軸の詳細を読み取ることができるソフトウェアエンジニアを雇い、開発者料金で支払い、文書化と文書化の維持を義務付けています。このライターはコードを読むことができ、尋ねるべき質問を知っており、必要に応じて詳細を記入します。QA部門と同様に、社内のドキュメント部門があります。

サードパーティにライセンスを付与できるため（コードを理解できるため）、コードの価値が高くなり、コードの監査と改善/リファクタリングが容易になり、コードを簡単に再利用できるようになりますソフトウェアのより軽量なバージョンを考慮に入れると、プロジェクトに新しい開発者をより簡単に紹介できるようになり、サポートエンジニアはあなたのために働くのが大好きになります。

これは決して起こりません。

さらに重要なことは、ドキュメントを書くことで将来の時間とフラストレーションを節約できることを彼らに納得させるにはどうすればよいでしょうか？

それはしますか？

ドキュメントには2つのタイプがあります。

便利なドキュメント

最終製品、API、サーバーのIPアドレスまたはURL名などの使用方法を文書化します。基本的に、頻繁に使用されるすべてのものは毎日使用されます。間違った情報はすぐに発見され、修正されます。簡単で簡単に編集できる必要があります（例：オンラインWiki）。

役に立たない文書

頻繁に変更されるドキュメント。非常に少数の人々がそれに興味を持ち、誰もそれを見つける場所を知りません。実装されている機能の現在の状態のように。または、3年前に更新されたSVNのどこかに隠されたワードドキュメント内の要件ドキュメント。このドキュメントは書くのに時間がかかり、後でそれが間違っていることを知るのに時間がかかります。このタイプのドキュメントに頼ることはできません。無駄です。時間を無駄にします。

プログラマは、役に立たないドキュメントを書いたり読んだりすることを好みません。しかし、有用なドキュメントを表示できる場合は、ドキュメントを作成します。頻繁に必要なすべての情報を書き込むことができるWikiを導入したときに、前回のプロジェクトで成功を収めました。

主な理由は意志の欠如とドキュメンテーションの機能に対する理解の欠如だと思います。考慮すべきドキュメントのクラスがいくつかあります。

製品/リリースのドキュメント

これは、「完成品」製品に当てはまるものです。これは単なるマニュアルではなく、README、変更ログ、HOW-TOなどです。理論的には、これらを書かずに済ませることはできますが、人々が使いたくない製品や、不必要に高価なサポートの負担になってしまいます。

APIドキュメント

これは、比較的静的であるべきものを説明しています。多数のコンシューマーがAPIをコーディングしている可能性があるため、APIの使用方法を説明する文章に価値があるほど十分に安定している必要があります。サポートされているパラメーター、戻り値、およびスローされる可能性のあるエラーを記述することにより、他のユーザーは適切な抽象化レベル-インターフェース（実装ではなく）でAPIを理解できるようになります。

コードコメント

現時点では、コメントに対する業界の意見は流動的であるようです。私が最初にプロのコーディングを始めたとき、コードを書くことになるとコメントは非常に重要でした。今、ファッションは非常に明確なコードを書くことであり、コメントは不要です。これは、一部には、多くの現代言語がはるかに高いレベルで書かれているという事実と、アセンブラーよりもJava、JavaScript、Rubyなどで読みやすいコードを書く方がずっと簡単だからだと推測するのは危険です、C、FORTRANなど。したがって、コメントのほうがずっと価値がありました。

私はまだ、コードのセクションの意図を説明するコメント、または特定のアルゴリズムがより明白なアルゴリズムよりも選ばれた理由に関するいくつかの詳細に価値があると信じていますtは実際に修正する必要があります）。

残念ながら、文書化しないというプログラマーの決定には、多くの利己主義、合理化、自己妄想が伴います。現実には、コードと同様に、ドキュメントの主な対象者は他の人です。したがって、ドキュメントを作成する（または作成しない）決定は、どのレベルでも、チームレベルで行う必要があります。より高いレベルの抽象化では、開発者以外の誰かがそれを行う方が理にかなっている場合があります。コメントレベルでのドキュメントに関しては、特に能力と経験が混在するチームでは、コメントの目的と意図について合意に達することを一緒に合意する必要があります。シニア開発者がジュニア開発者がアプローチできないコードを書くことは良くありません。適切に配置され、適切に文書化されたドキュメントによって、チームはより効率的に運用できます。

これが私の2セントです。

1. アジャイルマニフェストは、「包括的なドキュメントよりもソフトウェアを使用する」と述べており、誰もが「つまり、右側の項目に価値がある一方で、左側の項目をより重視している」とは言えません。

2. 残念なことにhttps://en.wikipedia.org/wiki/Code_and_fixに共通しており、ドキュメントはこのモデルでは機能しません（同期が取れなくなります）。

3. ソフトウェア開発業界は十分に規制されていません。ドキュメントを書くための法的要件はありません。

4. 自己文書化コードは現在の傾向です。

そうは言っても、良いドキュメントはたくさんあると思います。

ドキュメンテーションには時間がかかります。多くの開発者は、役に立たないよりも悪いドキュメンテーションで多くの慣らしをしていると思います。彼らは、文書化することでマネージャー（スケジュールのQA部分を削減し続けているのと同じ男）からトラブルが発生するだけでなく、それを含め誰にも役に立たないという考えを持っています。

少しまともなドキュメントは、将来への投資です。将来を気にしない場合（次の給料を超えて考えることはないか、それがあなたの問題ではないと思うため）、ドキュメントを作成するという考えは非常に苦痛です。

他の回答の多くは、少なくとも2種類のドキュメントがあることを強調しています。1つは他の開発者向け、もう1つはエンドユーザー向けです。環境によっては、システム管理者、インストーラー、およびヘルプデスクの担当者向けに追加のドキュメントが必要になる場合もあります。対象となる各対象者には、異なるニーズと理解レベルがあります。

（ステレオ）典型的な開発者を考えてみましょう：彼は選択によりコーダーです。彼は世間の目からキャリアを選び、主に自分と通信するキーボードの後ろで長い時間を過ごしています。ドキュメンテーションのプロセスはコミュニケーションの一形態であり、優れたドキュメンテーションを生成するために必要なスキルセットは、優れたコードを生成するために必要なスキルとは正反対です。

優れたドキュメントライターは、ユーザーの言語、管理の言語、サポートスタッフの言語、開発者の言語など、複数の言語でコミュニケーションを取ることができます。文書作成者の仕事は、コーダーが通信する内容を理解し、それを他のすべてのグループが理解できる形式に変換することです。

コーダーが優れたコミュニケーターになるために必要なスキル（書かれた、またはそうでない）を開発することを期待する場合、主要なスキルセット（コーディング！）を磨くのに費やされる時間は減少します。快適なゾーンから離れるほど（コーディングと他のコーダーとの通信）、タスクを適切に実行するためにより多くの時間とエネルギーが必要になります。プロのコーダーは、他のすべてを犠牲にして、主に彼のコアコンピテンシーに集中することを望むと合理的に期待できます。

このため、ドキュメント（インラインコードコメントを除く）は、コーダーではなくコミュニケーターに委ねるのが最適です。

コードを読むと、その仕組みがわかります。理由を説明できません。コメントが必要です。

コードを読むと、メソッドの名前とパラメーターのタイプが表示されます。セマンティクスや著者の正確な意図を説明することはできません。コメントが必要です。

コメントはコードの読み取りに代わるものではなく、コードに追加されます。

ドキュメントはコードのように実行されません。その結果、ドキュメントが適切で完全であることを確認するための効果的なフィードバックループがないことがよくあります。これは、コードコメントが腐敗する傾向があるのと同じ理由です。

Donald Knuth は、ソフトウェアの品質を改善する方法としてLiterate Programmingを推進し、コードを使用してドキュメントを効果的に記述しました。このアプローチを非常に効果的に使用したプロジェクトをいくつか見てきました。

個人的には、コードのパブリックAPIをできるだけ読みやすくするという現代の傾向に固執し、単体テストを使用して他の開発者の使用状況を文書化しようとしています。これは、APIを調査および発見できる形式にするという大きなアイデアの一部だと思います。このアプローチは、HATEOASがWebサービスで達成しようとしていることの一部だと思います。

些細な点ですが、ドキュメンタリーではほとんどないドキュメントを作成する一部の開発者にとって重要と思われる点は、入力できないことです。10フィンガーシステムの近似値がある場合は、簡単だからといってより多くのドキュメントを書く傾向があります。しかし、あなたが狩りとつつきで立ち往生している場合、あなたは失われます。私が雇うことに責任があるなら、これは実際に私がチェックするものです。

ドキュメントを読むのが嫌いな人は、ドキュメントを書くのが嫌いです。たくさんのプログラマーがドキュメントを完全に読まないようにできる限りのことをします。

執筆に集中せず、読書に集中してください。プログラマがドキュメントを読み、そこから物を吸収すると、彼らはその価値を理解し、もっと書きたいと思うようになります。

現在の仕事を開始し、以前に作業していた人々からハードウェアとソフトウェアのプロジェクトを引き継いだとき、システムを説明する100ミリ秒程度のワードドキュメントが与えられました。生産するのに何日もかかったに違いありません。多分二度見ました。そこには膨大な量の情報がありますが、システムについての実際の質問に答えることはめったにありませんでしたし、たとえそれを行ったとしても、コードを見る方が速くなりました。

そのような十分な経験の後、あなたは考え始めます、なぜ気にしますか？人々が決して尋ねなかった質問に答えるために時間を費やすのはなぜですか？あなたは、人々がドキュメンテーションでどのような情報を求めるかを予測することがどれほど本当に難しいかを理解し始めます。必然的に、役に立たない、不明瞭または明白であることが判明し、最も差し迫った質問に対する答えが欠けているという事実で満たされています。覚えておいてください、有用なドキュメントを作成することは、人間の行動を予測するための努力です。ユーザーインターフェイスの設計がテストとデバッグの複数の反復を経る前に成功する可能性は低いのと同じように、人々がシステムをどのように解釈するのかという期待にのみ基づいて有用なドキュメントを書くことができると考えるのは単純ですドキュメントとその言語がその解釈で果たす役割。

ドキュメンテーションを書くことへのプレッシャーのほとんどは、それが不快な雑用であり、不快な雑用をするように互いに罪悪感を抱くことを好むという事実から生じると思う傾向があります（「フィボイドスタッジを食べていません！」）。

しかしながら

ドキュメンテーションは、あらゆる点で絶望的だとは思いません。仕事を終える前に満たさなければならないこの余分な負担、急ぎの最後のちょっとした整理作業、そしてチェックすべき箱として、人々がドキュメントを見るのは、主に望みがないと思います。ドキュメンテーションは、あなたがいつもとにかく日々の側面に取り組むべきものです。電子メールはドキュメント作成に特に適した方法だと思います。新しい機能を追加するとき、それが何であるかを簡単なメールで数人書いてください。新しい回路図を描くとき、​​PDFを生成し、興味のある人に送信します。電子メールの利点は次のとおりです。

1. 人々は通常メールをチェックしますが、誰も「doc」というフォルダを歩き回りません。

2. 電子メールはコンテキストに存在し、その機能と関連機能、およびその時点で行われていたその他のことを議論する他の電子メールに囲まれています。

3. 電子メールは短くて集中的で、件名があります。

4. メールを使用すると、関心のある人がすぐに質問したり、

5. メールはすべて検索に使用され、メールクライアントは長年にわたってかなり進歩しているため、高度に検索可能です。

6. 電子メールの場合、少なくとも1人の他の人がそれを見つける場所を知っています。

理論的には、コード内のコメントも「いつもとにかくあなたの一日の側面」でなければならないように思えますが、正直なところ、コード内のコメントは決して読みません。理由は定かではありませんが、あまり役に立たないのは、おそらくコンテキストが不足していて、それによってメールが解決するからです。