4種類のドキュメントは、実践理論とトレーニング作業の2つの軸に沿って配布されます。
最近、2つのセンセーショナルな投稿が出ました。
そして、多くの人が「誰かが良いドキュメントの書き方を教えてください」と尋ねました。
私は専門家であるとは主張していませんが、私はそれが得意だと思います。
私は十分なコーヒーを飲みました、そして私は私が知っていることを説明しようとします。
TL; DR：ドキュメントを用意するだけでなく、特定のグループの人々の特定の問題を解決するためのドキュメントを作成します。
よく書く
まず、書くのが上手である必要があります。Drunken Revelationsの作者 はこの主張を明確に否定していますが、ほとんどの場合、うまくいかない可能性があります。あなたはトピックを取り上げて要点を見つけ、重要な詳細を示すことができなければなりません。これらの詳細は、適切に順序付けてから、明確な文に翻訳する必要があります。
もちろん、優れた執筆はドキュメントだけではありません。あなたはどんなタイプの文章でもこの分野であなたの能力をテストすることができます。あなたの家で何かを見つける方法を書くことができますか？短いスピーチを書いて頂けますか？この分野で作業する必要がある場合は、ドキュメント以外のものを書く練習をすることをお勧めします。ブログ記事を書いたり、短編小説を書いたり、友達に手紙を書いたり、なんでも。定期的に本を読んでいない場合は、今すぐ始めてください。あなたの脳は、あなたがあなたの特定の場合に何がうまくいくか、そして何がうまくいかないかを知ることができる前に、たくさんのよく書かれたテキストで訓練される必要があります。ライティングスキルとは大きく異なる編集スキルを身につける（ライティングが容易になり、編集スキルを信頼している場合は、自分自身をそれほどフィルタリングすることはありません）。
ドキュメントを書くための最も有用なアドバイスは、会話形式で書くことです。非公式のテキストから情報を認識する方がはるかに簡単です。
ドキュメントの種類
では、ドキュメントに戻りましょう。
ドキュメントにはさまざまな種類があり、人々は自分でロープを作り、ある種類のドキュメントを取得して別の種類のドキュメントを処理しようとします。ストレッチは2つの軸に沿って行われます。
- トレーニングのための情報VS仕事のための情報。
- 実用的なステップと理論的な情報。
（これは私の考えではありません。https：//documentation.divio.com/で見ました ）
実践的な手順を含むトレーニング情報は、チュートリアルと呼ばれます。実用的な手順が含まれていない場合、これは説明です。これらはどちらも初心者に適している傾向があるため、概念と用語（および背景情報）の説明に重点を置く必要があります。説明の観点から、上部に短い要約があると非常に役立ちます。
あなたが働いているときの情報のおかげで、誰かがすでに何が起こっているのかについての一般的な考えを持っていると仮定するのは安全です。
作業で使用される理論情報は、参照と呼ばれます。これには、各メソッドのドキュメントが含まれます。ヘルプドキュメントは、チュートリアルをホストするのにまったく役に立たない場所です。
これが理論でない場合は、このガイド。このガイドは基本的にチュートリアルに似ていますが、2つの重要な違いがあります。トピックにある程度精通していることを前提とし、目標は教えることではなく、特定のタスクを実行することです。チェックリストはクイックガイドですが、重要なステップを忘れがちな場合でも役立ちます。繰り返す必要のある手順がある場合は、ガイドを使用してください。手順を実行している人がタスクを完了する方法を知らない場合（他のチームの誰か、または1年以内にあなた）、これらは特に価値があります。
読者のニーズに基づいて、作成するドキュメントの種類を選択してください。コードが実際にはかなり自己文書化されている可能性があり、メソッドシグネチャを読み取ると、メソッドが何をしているかが実際にわかります。優れた。これは参考資料です。次に、他の3つのタイプを記述します。
あなたが持っているのが参照ドキュメントだけである場合、その情報は、基本に精通していない読者にとっては役に立たないランダムな事実の束になります。ヘルプドキュメントは、新しい読者が高速道路の地図を探しているときに交差点の詳細な説明を持っているようなものです。
実際には、5番目の種類のドキュメントがあると思います。パンくずリストです。これらは、読者が知っておくべきことを指摘する、コード内の小さなコメントまたはドキュメント内のメモ（またはカスタムリンターのエラーメッセージ）です。このコードが必要な理由を説明するJiraチケットへのリンクを含む小さなコメントを書くか、バグを修正するために実行するコマンドを人々に伝えることができます。ブレッドクラムはドキュメントに簡単に追加でき、時間を大幅に節約できます。
なぜ
当たり前のように見えることについて書くのを忘れがちです。もちろん、マイクロサービスを作成する方法については、なぜこれを行うのかを書く必要はありません。しかし、あなたはそうする必要があります。
これはあなたには明らかですが、読者にはわかりません。私たちはそれについて考えることに多くの時間を費やしてきたので、決定の背後にある理由は私たちにとって本当に明白に思えます。
あなたが何かをしている理由を説明するとき、あなたは決定に至ったステップを精神的にたどることを余儀なくされます。また、特定のトピックを紹介するための優れた方法でもあることがわかりました。
理由を説明しようとして立ち往生している場合は、記録しているものが突然消えた場合の世界がどのようになるか想像してみてください。誰が彼らが見るものを気にしますか？
その理由をストーリーで説明できればなおさらです。人々は物語の処理と記憶が本当に得意です。
ドキュメントの他のコメントが好きです。例えば。「それが良くないことはわかっているし、Xのように機能させたいのですが、Tチームが資料を更新する必要があり、非常に圧倒されているので、今のところはそれを使用しています。」それは、人々の頭の中にすべてをまとめ、何が起こっているのかを理解しているように感じさせるような情報です。
非技術的なトピック
技術的なトピックを文書化しているからといって、読者が技術的でないことを知る必要がないという意味ではありません。これが事実である理由は非常に深刻です。
以下を含むその他の有用な非技術的詳細：
- , (, -, , ).
- . « X , Y, Z»
- . « , , , ».
- , « , ...»
チュートリアルは、トピックに人々を慣れさせることを目的としています。人々はただ読むだけでなく、何かをするときによりよく学ぶので、これはそれをするための本当に良い方法です。
チュートリアルには、（他の種類のドキュメントと比較して）多くの投資も必要です。それらを書くことは、多くの人々がトピックを学ぶ必要がある場合にのみおそらく意味があります。数人の場合は、顔を合わせて（またはWebカメラからWebカメラに）会うのがおそらく時間の最も良い使い方です。
チュートリアルを書くときの罠は、すべてを説明しようとしています。確立されたルールのすべての技術的な詳細とすべての例外をリストしたいという衝動に抵抗してください。読者に基本的な仕組みを理解してもらいたいだけです。より経験豊富な人々のためのドキュメントのために、小さな詳細を残すことができます。
また、誰かがチュートリアルを操作しようとすると、チュートリアルが機能しないことがよくあります。作成した手順を（理想的には、すべてのコンポーネントがインストールされていない新しいコンピューターで）試して、それらが完全で実際に機能することを確認する必要があります。次に、誰かがこのガイドを使用する必要があるときに手順に従って、行き詰まった場所を確認します。
手順も時代遅れになりますので、問題のある方の声に耳を傾けてください。
ガイド
ガイドは投資収益率が高い傾向があります。箇条書きにステップをリストするのに10分を費やすと、次に何をすべきかを考える時間を1時間節約できます。
これは、これらの手順が何であるかを理解するのが難しい場合、または重要な手順をスキップしやすい場合に特に役立ちます。
プロセスを終えたばかりで、すべてをもう一度理解することを避けたいという動機があれば、ガイドを作成します。
説明とヘルプ
正直なところ、javadocスタイルのリファレンスドキュメントの価値についてはよくわかりません。もちろん、100万人があなたのレッスンを使用する場合は、袖をまくり上げて、すべてを細部まで文書化します。しかし、それがあなたのチームの読書だけである場合、彼らはあなたが書くことができるものの99％をすでに知っているでしょう。
説明は一般的に、特に理由の説明に焦点を当てている場合に、より役立ちます。デザインの作成につながるユーザーと技術的な制約を説明すると、デザイン自体を説明することをほとんど忘れることができます-背景情報を武器に、誰かがコードを読むことで自分でそれを理解することができます。コードを読むだけで（最終的には）構造を学ぶことができますが、この方法で理由を理解することは困難または不可能ですらあります。
文書化の実践
ドキュメントの作成には時間がかかります。多くの時間。誰かが「もっとドキュメントが必要だ」と言うので、今回ドキュメントに費やすのは魔法だけではありません。あなたはこれのために時間を取っておき、書くことに何時間も費やすべきです。いいえ、これは木曜日の夜を過ごすのに最も楽しい方法ではありませんが、そうしなければなりません。
か否か？ドキュメントは、役立つ場合にのみ作成する必要があります。より多くのコードを書くためだけにコードを書くことはありません（あるいは、そうするかもしれませんが、私はしません）。特定の問題を解決するためのコードを記述します。また、特定の問題を解決するためのドキュメントを作成する必要があります。
この「何か」は、新しい人々がチームに活力を与え、チームのバスファクターを減らし、手順を忘れることによる間違いを避け、行動を実行するときに人々の時間を節約し、コンテキストを提供し、合意を構築し、失礼だが重要なことを書き留めるのを助けるために実装できます詳細などドキュメントを書いている理由がわからない場合は、それを行わないでください。理由がわかったら、解決する問題に適切なドキュメントを選択します。
聖なるものすべての名において、このような文書を書かないでください：
/**
* @param customer The customer
* @param order The order
* @return The price
*/
public Price getPrice(Customer customer, Order order) {}
これは無意味であり、読者に精神的にコメントをスキップするように教えます。実際に役立つものが含まれているコメントはスキップされます。何も言うことがない場合は、言わないでください。
コードのようなドキュメントは維持する必要があります。あなたはそのストレージの代金を払わなければなりません。あなたはそれをサポートするために時間をかけなければなりません。幸いなことに、これは通常、コードを維持するよりもはるかに安価です。ウィキ全体を読んで今すぐ問題を修正するために必要なのは、月に数時間だけです。
ヒント：ドキュメントに「アーカイブ」セクションを作成し、廃止された資料をそこに移動します。それは歴史的な文脈を保存し、単にドキュメントを削除するよりも優れており、疑いを持たない読者にだまされる必要はありません。
時間を節約する1つの方法は、他の作業をドキュメントに変えることです。システムと統合する方法を同僚に説明する必要がある場合は、Slackに書き込んだ内容をドキュメントにコピーします。プロジェクトのドキュメントを作成した場合は、そのいくつかのセクションをドキュメントにコピーして、10分かけて準備します。コードレビューでレビュー担当者に何かを説明する必要がある場合は、Githubでのコミットではなく、コード内のコメントで説明してください。 Jiraチケットは、タスクを完了する必要がある理由を説明していますか？かっこいい、これをコピーすれば、ドキュメントが手に入ります。 （そうでない場合は、質問者に書いてもらいましょう！）
質問をする場所を人々に伝えます。「ご不明な点がございましたら、Slackの＃team-channelまでお問い合わせください」と約15秒でお書きいただけます。これにより、混乱した場合に時間を節約できます。私の意見ではかなり良い見返りがあります。
コーヒーがなくなったので、そこでやめます。