https://document360.com/blog/technical-documentation/
ドキュメンテーションは常に物議を醸すテーマです。私の経験では、ソフトウェア エンジニアリングでは、ソース コードや出荷機能などの成果物のビジネス価値に重点が置かれており、それ以外には重点が置かれていないからです。「アジャイル実践に必要なドキュメントだけを書くべきだ」「設計ドキュメントを書くのは時間の有効活用ではない」という意見をよく聞きます。これらの主張にはある程度の真実があり、多くの場合、開発中のドキュメントが、そのドキュメントが提供することを目的とした人々に永続的な価値を提供していないことが原因です。
別のソフトウェア エンジニアが、他の人が書いた不十分なドキュメントについて文句を言うのを聞くと、なぜわざわざドキュメントを書く必要があるのかといつも疑問に思います。時々、非常によく書かれた文書に出会うと、なぜそれを行う価値があったのかを思い出します。残念ながら、これは、多くの人にとっては明白であっても、一部の人にとってはそうでないことを指摘しています。ドキュメンテーションは科学ではなく芸術であり、ほとんどのソフトウェア エンジニアはアーティストではありません。
実際、効果的な文章を書くには、コンピュータに何かを命令する際の論理と正確さを訓練された人には自然に身につかない多くのスキルが必要です。もし私個人が、学習もせず、上手に書けるようになろうとしていれば、コードが何をしているのかを理解するために「コードを読む」陣営にいることになり、コメントやその他の形式のドキュメントを気にする必要がなくなるでしょう。しかし、ソフトウェア エンジニアとしての 20 年間の中で、特定の方法が実装される理由を説明する適切なコメント、または他のアプローチが拒否された場合のトレードオフを説明する文書があれば、膨大な時間を節約できることがわかりました。手間が省けるため、コードベース内の内容をできるだけ早く適応して変更できるようになります。
皆さん、そこにこそ価値があるのです。
優れたドキュメントは聴衆の心に残り、理解を促進する視点を提供します。
はじめにはじめに
お話の時間です！
Friendster にいたとき、私はソフトウェア エンジニアリング グループに参加しました。このグループは、生産上の多くの課題と、所有する主要な知的財産を構築しながら機能を提供するためのペースの速い環境を抱えていました。当時、Friendster は、ユーザー (または「友人」) 間の接続を維持するための中核技術である「グラフ サーバー」と呼ばれるものの特許を保持していました。
このアイデアは、隣接関係リストを維持し、それを Memcache サーバーのプール全体で「シャード」するというものです。プールを構成して、プール サイズ 3 の N 個の Memcache サーバーのリングを作成すると、次のようになります。 a データのコピーが存在する、論理的に隣接する 3 台のサーバーのプール。これにより、Memcache サーバーの 1 つに障害が発生した場合に備えて冗長性がもたらされますが、クライアントは 3 つのサーバーのうち 1 つを選択して読み取りデータを要求し、それを正しいパス上の 3 つのサーバーすべてに書き込むこともできます。この設計には多くの利点がありますが、それらはこの記事の焦点ではありません。)
このグラフィックス サーバーは、復元力、効率、パフォーマンス、およびスケーラビリティを向上させるために私が取り組んだコンポーネントです。2007 年から 2008 年にかけて使用していたツールを使用して、この目標の達成にほぼ成功しました。
また、最初から適切なドキュメントもありませんでした。
グラフィック サーバーは、HTTP 1.0/1.1 リクエストを処理する C++ サービスとして実装されており、HTTP URI は特定の操作を表します。これは、変更が許可されておらず、当時はリソースベースの API 設計がまだ一般的ではなかったため、正確には REST API ではありませんでした。この実装には十分なコメントがなく、この方法で実装する理由に関する設計上の決定が文書化されていません。
最初のパートではこれについてある程度説明し、第 2 パートでは代替案をゼロから作成するプロジェクトをどのように開始したかについて説明しました。このセクションでは、ドキュメントのギャップをさまざまな種類のドキュメントで徐々に埋める方法について説明します。
どのような種類の書類がありますか?
ドキュメントにはさまざまな種類があります。実際、あなたが今読んでいるものもドキュメントの 1 種類です (これをナレッジ ベースの記事と呼ぶ人もいるかもしれませんが、ナレッジ ベースとその構築方法については次回説明します)。この記事では、一般的なソフトウェア エンジニアリング プロジェクトに関連するドキュメントをいくつか紹介します。これらは：
- インライン/コード ドキュメント: これらのファイルは通常、コメントの形式でプログラム ソース コード内に存在し、隣接するコードの特定の側面を説明します。場合によっては、これらのファイルは、プログラム構造とともに自動ツールで表示するために、HTML や PDF ファイルなどの外部成果物として解析および抽出されます。
- システムドキュメント: これらは通常、システム (図の有無にかかわらず) と相互作用するコンポーネントを説明する個別のドキュメントです。場所によっては、これらの文書はシステム設計文書、技術設計文書、またはソフトウェア設計文書と呼ばれ、事前定義されたテンプレートに従っているか、少なくともシステムレベルの属性をカバーしています。
- ユーザーマニュアル: これらは、ユーザーがシステムとどのように対話するか、期待される結果、エラーモード、および一般的な使用法を示す例を説明するユーザー向けの文書です。
- 操作マニュアル: これらは、システムがどのように動作するか (構成、展開、監視の方法など)、およびシステムが期待どおりに動作しない場合のトラブルシューティング方法を説明するオペレーター向けの文書です。
上記の範囲に当てはまらないドキュメントもいくつかありますが、それでも役に立ちますが、通常は必要に応じて生成されます。これらには次のものが含まれます: アーキテクチャ上の決定記録 (トレードオフと下された決定を文書化)、技術的アドバイス (一部のプロジェクトでは、これらは文書化またはエンジニアリング作業追跡システムのチケットです)、ユーザー ストーリー (機能仕様の欠落またはサポートされる予定の機能) 、また、欠陥レポートや変更リクエストも含まれます（場所によっては、正式なプロセスで、以前に合意された機能または提供された機能からの逸脱を文書化する必要がある場合があります）。それらのどれにも立ち入りませんが、以下で説明するのと同じ理由ですべてが価値があるのでご安心ください。
なぜドキュメントを書くのか?
これは常に答えのない質問ですが、多くの人はあえて質問しないか、すでにある程度の決意を持っています。私がここで、効果的なドキュメントを書くことは追求する価値のある目標であると確信していただけるような視点を提供するためにここにいます。
- 特定のアルゴリズムが使用される理由、フィールドの順序がどのように重要であるか、さらにはなぜそのような名前が付けられているのか、どのような代替名が使用できるのかを説明すると、システムが読みやすく、理解しやすくなります。
- ソフトウェア エンジニアリングのようなチーム スポーツでは、コンセンサスを達成して維持することで、チームが同じ目標に向かって協力することができます。コードの構造を理解していないチームに所属し、お互いの仕事を踏みにじり、良好なコミュニケーションを維持できないことほど最悪なことはありません。自分の感覚よりも時間に余裕のある人が、元の構造の目的を理解せずにコードの 60% を書き直すと、チームの士気が低下し、チーム環境が有害になります。あるいは、その際、なぜそのような変更が必要なのかについてのコミュニケーションがありません。同じ認識を持つことで、全員が参加し、仕事の目標に合わせて調整することができ、より効果的なチームワークとコラボレーションにつながります。
- 問題、利用可能な解決策、全員を成功に導くための価値を提供する計画を文書化します。少なくともそうすることで、あなたとあなたのチームにとって、どのような問題を解決しているのか、どのような解決策が利用可能なのか、そしてどれを選択したのか、そしてそれを読んでいる人々 (チーム、利害関係者、経営陣、顧客) にとって、どのように意図しているのかが明確になります。価値を提供するために。これを書き留めて関係者の同意を得ることができない場合、ただコーディングに没頭してすべてがうまくいくことを願っているだけでは、あなたの仕事は困難になるでしょう。希望は戦略ではありません。
これらは、ドキュメントを書くことが重要である理由のほんの一部です。不足している理由は他にもあると思いますが、次のセクションでは、上に挙げた理由に基づいて有効なドキュメントがどのようなものであるかを説明していきます。
役立つドキュメントとはどのようなものですか?
有効なファイルには 4 つの主要な属性があります。
- 明瞭さ
- 完全
- 一貫性
- 関連性/最新であること
これらはすべて、文書の対象読者の観点から評価される必要があります。上で示唆したように、ソフトウェア エンジニアリングのドキュメントには通常、次の 3 つの主な対象読者がいます。
- ユーザー
- ソフトウェアエンジニアソフトウェアエンジニア
- ユーザーオペレーター
これらの対象者は同じグループの人々である可能性があります (たとえば、ソフトウェア ツールは、システムを自分自身で実行するソフトウェア エンジニアを対象としています) が、焦点は明確であり、相互に独立している可能性があります。
私が長年にわたって学んだ効果的な文章の原則の 1 つは、「聴衆のことを念頭に置く」ということです。
次のセクションでは、主要な属性のそれぞれと、文書が有効かどうかを確認する方法について説明します。
明瞭さ
何かが明確であれば、それは明確であり、誤解の余地はありません。
明確に書くには、一点に焦点を当て、その意味を邪魔することなく言葉を使ってその意味を伝えることが必要です。
専門用語の使用は極力避け、専門用語を使用する場合は、統一された場所（用語集など）で定義し、意味を明確にしてください。
作成するドキュメントを明確にするために私が行っていることをいくつか紹介します。
- 聴衆に対してドキュメントをテストし、わかりやすさに関するフィードバックを求めます。
- 最大限に明確にするために、信頼できる人に文書の批評を依頼します。その人が問題や解決策の分野にあまり精通していない場合に役立ちます。これは自分の偏見や盲点を特定するのに役立ち、将来のドキュメント作成スキルの向上に役立ちます。
- 同じ文/段落の異なるバージョンを書いて、聴衆の観点からどちらがより明確であるかを確認し、どちらかに決定します。これには時間がかかりますが、これまではこれにより品質の高い結果が得られたことがわかりました。
明確に書く目的は、理解の障壁を減らすことです。明確に書かれたドキュメントは、人々がそれを読んでそのドキュメントの内容をよく理解し、当初よりも多くの疑問を抱いた場合に効果的です。
ドキュメントを読んだ後に他の人が質問するような場合は、ドキュメントが十分に明確ではありません。
完全
ドキュメントがソリューションの関連部分をすべてカバーしていれば、対象読者の観点からはドキュメントは完成したことになります。
視聴者とオープンなコミュニケーションが取れている限り、関連する部分を理解するのは難しくありません。顧客を想像するのは難しいので、実際の顧客と話すのが良いでしょう。または、ソフトウェア エンジニアとしての視点を取得し、他のソフトウェア エンジニアも同じ懸念を抱いていると想定し、完全なドキュメントを作成することはできません。
これには時間がかかる可能性があり、よく反対されることです。ソフトウェア エンジニアは、問題解決の仕事とはみなされていないため、ドキュメントを書くのが一般的に苦手です。しかし、本当に解決すべき問題として扱うなら、ほとんどのソフトウェア エンジニアはプロセスを自動化するか、完全に解決する方法を見つけるでしょう。
Google では、パブリック インターフェースのドキュメントに関して高い基準を設けています。何百万行ものコードがあり、機能が十分に文書化されていることに驚きました。さらに良いことに、何かが不完全な場合、誰かがそれを問題として扱い、できるだけ早く修正しようとします（窓が割れたりすることはありませんが）。
聴衆の観点からいくつかの重要な質問に答えると、ドキュメントが完成したことがわかります。
- このソリューションの特徴は何ですか? コード内の関数の場合、パラメーターは何で、結果にどのように影響し、どのように失敗し、何をするのでしょうか? ツールの場合、どのようなオプション/コマンドがあり、入力をどのように受け入れ、どのような形式で、出力は何ですか?
- さらに詳しい情報が必要な場合、詳しいドキュメントはどこにありますか? たとえば、コマンド ライン ツールからは、いくつかの情報を含む `-help` オプションが存在する可能性がありますが、より包括的なドキュメントへのリンクも存在する可能性があります。ユーザー マニュアルが利用可能なすべてのオプションをカバーしていない場合は、インライン コメントから生成されたオプションに関するオンライン ドキュメントが役立つリンクになる可能性があります。
- このソリューションはどのように機能するのでしょうか? 実行する必要がある依存関係はありますか? 特定のハードウェア/ソフトウェア パッケージでのみ動作する機能はありますか? ユーザーがソフトウェア エンジニアではない場合でも、ソフトウェアがどのように機能するかを知りたがっていることに驚かれるかもしれません。そのため、完全を期すために、この情報はドキュメントの一部である必要があります。
- このソフトウェアは誰のためのものですか? これを明確に文書化することも完全性としてカウントされます。
- このソフトウェアはいつ使用すればよいですか? 別の言い方をすれば、このソフトウェアはどのような問題を解決しようとしているのかということです。
- なぜこのソフトウェアが存在するのでしょうか? トレードオフの問題があります。これは、すでにあるものが要件に適合しないために構築されているのでしょうか? これらの要件 (文書化されたもの) は何ですか?
おそらくこれは、私のようなソフトウェア エンジニアが見て、「難しすぎます。この問題に対する 80/20 の解決策はありますか?」と言うでしょう。私の答えは「はい」です。しかし、ファイルの 20% を知ると、80% を生成するのがより困難になります。懸念事項を 100% カバーするよりも、価値の向上を目指します。
ファイルが長くなくても完成するというわけではないことに注意してください。
一貫性
効果的な文書では、全体を通して同じ語彙、スタイル、トーンが使用されます。
Google では、コードだけでなくパブリック インターフェースのドキュメントもカバーするスタイル ガイドを用意しています。全員が遵守し、お互いに責任を負う一貫したガイドラインがあるため、これはドキュメントを読んだり書いたりするときに非常に役立ちます。私がそこにいることで最も大切にしているのは、このコミュニティと文化的な側面でした。
独創性や創造性の余地はありますが (たとえば、ユーモラスなユーザー マニュアルや遊び心のあるユーザー マニュアルを作成することもできます)、ドキュメントへのアプローチは一貫しています (たとえば、各プロジェクトには README.md が必要です)。この一貫性により、相互リンクされたすべてのドキュメントが検索可能になり、簡単に発見できるようになります。あるプロジェクトが別のプロジェクトに依存している場合は、ドキュメントのリンクや実装をたどって、関係が何であるかを判断できます。
設計文書などの独立した文書では、文書の読者が同じ内容に対して異なる単語を使用することで気を散らす必要がないように、自己一貫性が重要です。複数の文書で同じ単語を使用すると、関連分野に精通した読者が混乱する可能性が低くなります。
ドキュメント内で使用されている紛らわしい用語について読者が苦情を言わなければ、ドキュメントに一貫性があることがわかります。
関連性/最新であること
古いドキュメントほど最悪なものはありません。
良く言えば、ドキュメントは少し間違っており、最悪の場合、積極的に読者を誤解させます。これまでのキャリアの中で、期限切れのドキュメントを単純に削除するために、そのドキュメントにプル リクエストを送信する必要性を何度も感じてきました。ありがたいことに、私がこれを自分でやったとき、プロジェクト リーダーは感謝してくれました。
文書の価値は、その正確さと関連性によって決まります。ドキュメントが実装の現実を説明しなくなった場合、そのドキュメントはもはや正確でも関連性もありません。同様に、ドキュメントがプロジェクトの方向性ではなくなった方向を指している場合、そのドキュメントはもはや正確でなく、関連性もありません。どちらの場合でも、ドキュメントの正確さと関連性を維持するためにドキュメントを作成することは、ソフトウェア エンジニアリングの通常のプロセスの一部である必要があります。
C++ ベースのグラフィック サーバーを書き直す取り組みでは、実装を変更するたびにドキュメントも変更するようにしました。Doxygen を使用してドキュメントと UML 関係を生成し、これらのドキュメントをコードの横に隠して最新の状態に保ちます。当社には、用語、プロジェクトの目標、提供した機能を定義する Wiki があります。パフォーマンス データも Wiki にあります。製造テストと結果もそこに記録されます。
誰かがプロジェクトに参加しようとしている場合、これらの文書が彼らがプロジェクトに参加し、自分のペースで結果を達成するのに十分であることを確認します。もちろん、私たちは彼らを支援しますが、運用チーム、製品チーム、他のエンジニアリング チーム、および経営陣とのコミュニケーションには文書に大きく依存しています。
Google では、コードベースでホストされているドキュメントがいつ最後に更新されたかを自動的にチェックし、ドキュメントを所有するチームにバグを送信して、適切にレビューして更新できるように構成できるシステムを与えられました。これにより、文書管理がシステム保守の一部となり、文書管理を尊重して扱うことができるようになります。
古くなった文書は歴史の遺物となります。この文書から私たちが得るべきものは現実の反映です。
オープンソースのドキュメント
ドキュメンテーションの重要な成功事例と、ソフトウェア エンジニアとユーザー コミュニティにとってのその価値は、効果的なドキュメンテーションを提供することでオープンソース プロジェクトがどのように存続し、消滅するかにあります。
たとえば、Rust、Python、OCaml、Zig、C#、Java、LLVM コンパイラ ツールチェーンなどのプロジェクトのドキュメントの品質は、プロジェクトに取り組むユーザーやソフトウェア エンジニアに価値を提供するためのモデルです。
たとえば、Cloud Native Computing Foundation (CNCF) のプロジェクトには、満たす必要のあるドキュメントの品質基準があります。それには理由があります。ほとんどの最新のソフトウェア エンジニアリング プロジェクトを推進するこれらの基礎的な部分では、数を減らすために高品質のドキュメントが必要です。新しいシステムの保守と運用の負担が軽減されます。たとえば、Kubernetes、gRPC、Istio には、開発者が最新のシステム アーキテクチャを立ち上げて実行できるようにするための優れたドキュメントが用意されています。
これらのシステムに関する高品質のドキュメントにアクセスできず、コードから学習しなければならないことを想像してみてください。もし私がそのような労働条件で働くよう求められたら、他の業界に移るでしょう。
コードはオープンで利用可能ですが、これらのプロジェクトのメンテナーとその周囲のコミュニティが、サービスを提供する聴衆の利益のために効果的なドキュメントに十分な投資を行っていることは素晴らしい先見の明です。
結論
私の 20 年のキャリアの中で、ドキュメントを書くのが好きではなかったと言ったら嘘になります。私は個人的に、効果的なドキュメントを書くことは、すべてのソフトウェア エンジニアが投資すべき重要なスキルであると信じています。それは、それがもたらす価値のためだけでなく、このスキルがソフトウェア エンジニアリングのさまざまな側面にどのように応用されるかという理由からでもあります。
他の人が理解できる形式でアイデアを書き留めることができることは、現代のソフトウェア エンジニアリングの鍵です。ソフトウェア エンジニアリングのチーム スポーツは、実際にコードを手作業で記述することよりも、コラボレーション、文書化、問題解決を重視するものになるだけです。実際、現代のソフトウェア エンジニアリングでは、コードを書くことはもはや重要な部分ではありません。アイデアを書き出し、同僚に批判され、計画を立てて完成させ、共通の目標を念頭に置いてできるだけ早く実行します。このプロセスに価値があります。
効果的なドキュメントを優先すると、オープンソース ソフトウェアで良い結果が得られます。あなたとあなたのチームが同じパターンに従って最新のソフトウェア エンジニアリングを実践することを妨げるものは何もないはずです。
必要に応じて、ChatGPT にドキュメントを作成させてみることもできます! :)
追記
このシリーズの記事をお楽しみいただければ幸いです。この記事が気に入ったが、最初の 2 つの部分をまだ読んでいない場合は、ここから見つけることができます。
http://t.csdn.cn/ncXXN