「技術文書の書き方は？「コメントは意外です。「良いデザインドキュメントの書き方」に関する記事は敵意に満ちています。
インターネットの新時代で自分の考えが時代遅れになっているかどうかはわかりませんが、文書を書くことは少数派になっているようです。いずれにせよ、あなたの意見を明確に表現してください。
この記事のすべての意見は個人的な意見であり、あなたが正しいと思うことを共有するための「判断」はありません。
Voiceover：次のテキストの資料、「技術文書の書き方」のスクリーンショット 「コメントでは、アバターと名前は隠されています。
1.
技術文書の書き方は？「コメントの中で最も似ている点は、技術文書を書かないことです。この方法でのみ、上司はtaをさりげなく置き換えず、taを「かけがえのない」ものにするからです。
しかし、「職場のかけがえのないもの」とは、「隠された穴をたくさん埋めた。隠された穴がどこにあるかしかわからないので、かけがえのない」
という意味ではありません
。
むしろ、
「私には他の人にはない中核的な競争力があります。それは態度、専門能力、または見栄えの良さかもしれません」という意味です。
サンシャインポジティブエネルギー：
職場で一生懸命考え、「穴を掘る」ことで「鉄丼」を維持するためには、どこでも食べられるように、コア競争力を高めるために一生懸命働くほうがよいでしょう。
2. 2つ
目の視点は、他の人が見られるように、上司、顧客、コミュニケーションを取りたい人、プロジェクトを引き継ぎたい人のために文書が書かれているということです。プロジェクト参加者はドキュメントを書く必要はありません。
なぜデザインドキュメントを書くのですか？
コードを書く前に、自分自身でより明確に考えるようにしましょう。
プロジェクトの場合は、情報の一貫性を確保し、プロジェクトの制御性を確保し、プロジェクトのリスクを軽減します。
チームの場合は、知識の蓄積と継承を確保します。
プロジェクトに関与するサブシステムの数、各サブシステムに関与するモジュールの数、モジュール間の依存関係、相互に提供する必要のあるインターフェースの数、各インターフェースのパラメーター、インターフェース実装プロセスでのアップストリームとダウンストリームの相互作用の程度、コアロジックに使用されるテクニカルソリューション実現...関連する技術者はすべてを知っていますか？
多くの自信を持っているテクノロジーの神々は、彼らが理解していると「考えている」が、理解していない。実際、彼らは単に理解していない。
多くの「はっきりと話す」が「はっきりと書かれていない」は実際には理解されていません。
プロジェクトと技術的な問題が言葉で論理的に記述されている場合にのみ、それは本当の考え方が明確であることを意味します。
Voiceover：紙に着地すると、デザインに多くの問題が見つかります。
ドキュメントはどのようにして情報の一貫性を確保し、プロジェクトのリスクを軽減しますか？
簡単な例を挙げると、PHPエンジニアは注文情報を取得するためのHTTPインターフェイスを提供し、後でIOS / Android / FEエンジニアと調整する必要があり、QAエンジニアもテストする必要があります。
HTTPインターフェースを紙に書く必要はありませんか？
http://daojia.com/order/getinfo?oid=${oid }
cookie：uid = $ {uid}
cookie：token = $ {token}
…
RESTFULインターフェイス形式、入力および出力形式、情報はPHP / IOS /です。 Android / FE / QAエンジニアは明確な情報を必要とします。そうしないと、関連するR＆D共同デバッグおよびテスト作業が実行されません。この情報は毎回口頭で伝達する必要がありますか？
プロジェクトが開始されてから1年後、インターフェイスを繰り返しアップグレードする必要があります。毎回コードを確認する必要がありますか？
ボイスオーバー：メモは非常に重要です。メモとドキュメントは競合しません。同じ問題を解決することはできません。
サンシャインポジティブエネルギー：
良いドキュメントを書くことは、あなた自身にとっても、プロジェクトにとっても、チームにとっても良いことです。
3. 
3番目の視点は、書く時間がないということです。
神は公平で、時間が節約され、デザインについて考えることに多くの時間を費やし、コーディングは間違いなくスムーズになり、多くのコミュニケーション/ラングリング時間を削減でき、プログラムの変更によって引き起こされる多くの追加の変更/共同デバッグ/テスト時間を節約できます、これにより、長期的なメンテナンスにかかる時間を大幅に節約できます。
サンシャインポジティブエネルギー：
運動したいのですが、時間がありません。
英語を学びたいのですが、時間がありません。
いい文書を書きたいのですが、時間がありません。
モーメント、ヘッドライン、ビブラト、追跡シリーズを読む時間があります。時間があります。
言い訳を拒否し、一緒に行動し、技術文書を書きます。
第4に、
要件は急速に変化し、ソリューションは急速に変化し、ドキュメントはゆっくりと書き込まれるという別の観点があります。したがって、ドキュメントを書き込むことは無意味です。
問題を議論するときは、まず合理性について話し合います。それが合理的であるが困難がある場合は、困難な解決策を検討します。通常、それはそのような論理であるはずですよね？
理由：
「要件は急速に変化し、ソリューションは急速に変化し、ドキュメントはゆっくりと書き込まれます。」
したがって：
「ドキュメントの書き込みは役に立たない」
ロジック自体が間違っています。
私たち（特に話し、決定する権利を持つ技術リーダー）まず第一に、私たちはそれについて考えるべきではありません：
- 需要は常に変化していますが、それは合理的ですか？
- 計画は常に変わります、それは合理的ですか？
- ゆっくりと文書を書くのは合理的ですか？
- ドキュメントがないのは合理的ですか？
最初にこれらの質問を自問してはいけません。
「ドキュメントの書き込みが遅くて不合理だ」と思ったら、次に考えてみるべきではありません。
なぜ書き込みが遅いのでしょうか。従業員の意欲や能力の不足、ツールの使い方の悪さなどが原因ですか。
- 意欲が足りない場合、従業員の意欲を高める方法
- 能力不足の場合、スタッフの能力を向上させる方法
- ツールが良くない場合、ツールの効率を最適化する方法
...
存在は合理的ではないかもしれません：
- 「奴隷」は何千年も前から存在しているので、奴隷になるのは合理的ですか？
- 「総需要は変化し、計画は常に変化し、文書はありません」が、これらは必然的に合理的ですか？
サンシャインポジティブエネルギー：
テクニカルリーダーとして、あなたのチームの兄弟姉妹は悲惨な状況にありますが、あなたは行動しません。あなたは罪悪感を感じませんか？不合理な現状を変え、技術的な雰囲気を作り出すために、あなた自身の能力の範囲内で行動してください。
V. 
1つの観点：他の人が書いていない場合、自分で書いて、お金を失う。
1つの観点：上司は文書を必要とし、コード農家はそれを必要としません。
1つの観点：給与が非常に低いので、書かないでください。給与が上がる場合は、書いてください。
1つの視点：ドキュメントを書くことは他を達成することです。
ボイスオーバー：コメントが多すぎるので、1つずつ公開しません。「技術文書の書き方」を直接参照してください。「下部にコメント。
記事「技術文書の書き方は？「、コメントのポイントのほとんどは「役に立たない」ということで、私は予想もしていませんでした。
Voiceover：みんながそう考えるのではなく、ただ私について冗談を言っていることを願っています。
でも、私がいつも主張してきたことは正しいと思いますか？
2011年に転勤した際、真面目な「モジュールの引き継ぎ」を行い、当時担当していた13のモジュールを整理してまとめました。転職後は、引き継いだエンジニアがプロジェクトやモジュールに対応できなくなるのではないかと不安で、非常に罪悪感を覚えました。
異動から数ヶ月経っても、モジュールを引き継いだ同僚に質問があれば、同僚のデスクに行って質問に答えます。
終わり：
誰かが文書を書くかどうかに関係なく、これは正しいことだと思います。私はそれを行います。
他のリーダーが文書を必要とするかどうかに関係なく、私のチームではそうします。
何年も経った後、おそらくあなたは他の人とは違う選択をしたからこそ、他の人とは違う自分になっていることに気付くでしょう。
相互励まし！
アーキテクトの道路共有着陸可能な技術
関連する提案：
「技術文書の書き方は？「
需要は常に変化します、それは合理的ですか？」》
研究：
上司は不合理なことをしますか？