プロジェクトの中には、長く活動を続けるものもあれば、早期に消滅してしまうものもあります。その違いは、多くの場合、ドキュメントの有無にあります。厳密かつ賢明なドキュメント作成は、プロジェクトに必要な推進力を与えます。ドキュメント作成は、開発と同等に重要なタスクとして扱うべきです。以下では、その理由と適切な作成方法を説明します。

開発者はしばしば、自分のコードが十分に自己文書化されているため、追加のドキュメントは不要だと誤解しがちです。この過信は大きな代償を払う可能性があります。不十分な、あるいは質の低いドキュメントはプロジェクトを台無しにする可能性があります。適切なドキュメントがなければ、ユーザーはプロジェクトの目標や正しいワークフローを理解できません。その結果、オープンソース製品の採用に疑問を抱くことになりかねません。

ドキュメントの作成はプロジェクトの初日から始まります。

ドキュメント作成は副次的なタスクではなく、コード開発と管理と同等の主要タスクであるべきです。コミュニティスレッド、Stack Overflow、QuoraのQ&Aを通じてコン​​テンツが広く発信されることで、ドキュメントは「真実の源」として機能します。直接的な情報を求める貢献者のニーズを満たし、エンジニアに必要な参考資料を提供する必要があります。また、ステークホルダーに基本的な計画を伝えることも重要です。優れたドキュメントは、製品の継続的な改善と開発を確実なものにします。

ソフトウェア製品をリリースする際には、コードだけでなく、質の高いドキュメントもリリースします。これは、多くの優れたドキュメントを備えたオープンソースプロジェクトが採用している重要なコンセプト、「コードとしてのドキュメント」につながります。

ドキュメントとコード

今日、ドキュメントはもはやMicrosoft WordやPDFファイルとして保存されていません。新たな需要は、すべてのドキュメントがバージョン管理システムを通じて追加され、継続的に公開される、バージョン管理されたドキュメントです。Read the Docs（LCTT注：ドキュメントの作成、ホスティング、閲覧のためのプラットフォーム）によって普及したこのコンセプトは、現在、ほとんどのドキュメントチームにとってコンテンツ戦略の重要な部分となっています。

BugzillaやGitHub Issuesなどのツールは、保留中のドキュメント作業を追跡し、メンテナーやユーザーからのフィードバックを収集してドキュメントのリリースを検証するために使用できます。外部レビューはドキュメントの品質を検証し、継続的なリリースを保証するために使用できます。これにより、コードだけでなくドキュメントも継続的に改善され、迅速にリリースされることが保証されます。

標準化された手順に従わない場合、文書ごとに内容が異なってしまうことをご承知おきください。これにより混乱が生じ、正しい情報を得ることが困難になる可能性があります。

何が「混乱」とみなされるのでしょうか？ほとんどのドキュメントがベストプラクティスに従っていない場合、不整合が生じ、さらに混乱を招きます。では、混乱したオープンソースドキュメントをどのように整理すればよいのでしょうか？

整理されていないオープンソースドキュメントを整理する

「ドキュメントスタイルガイド」に従うことは重要です。スタイルガイドとは、コンテンツの作成と提示に関するガイドラインの集合体です。個人ライターであっても、大規模なドキュメントチームのメンバーであっても、スタイルガイドはドキュメントのスタイル、アクセント、トーンの一貫性を維持するのに役立ちます。

Red Hatスタイルガイド、Googleドキュメントスタイルガイド、Appleスタイルガイドなど、人気のスタイルガイドはいくつかあります。どのように選べば良いでしょうか？まずはニーズを明確にすることから始めましょう。他のオープンソースプロジェクトと要件が大きく変わらない場合は、既存のスタイルガイドに従うか、まずスタイルガイドを選択してからニーズに合わせて修正することもできます。構文関連のガイドラインやコンテンツルールは大部分が共通している可能性が高いですが、全体的な用語は異なる場合があります。

プロジェクトでは、これらのスタイルガイドラインを自動的に適用する必要があります。そのためには、ローカルの継続的インテグレーション（CI）サービスと統合されたValeを利用できます。Valeは、ドキュメントがスタイルガイドラインに厳密に準拠していることを保証できます。

ドキュメントの種類:

• Readmeファイル：基本的なインストール手順と使用方法が記載されており、オープンソースドキュメントの中でも最も重要な部分の一つです。潜在的なユーザー/開発者とプロジェクトをつなぐ最初の接点となります。
• リファレンス ガイド: すぐに作業を開始するのに役立つ基本的なリファレンス マテリアルや、プロジェクトの貢献に関連するドキュメントなどが含まれる場合があります。
• ユーザードキュメント：これはプロジェクトの使い方を説明する最も基本的なドキュメントです。ユーザードキュメントがなければ、ほとんどの人はプロジェクトの使い方に戸惑ってしまうでしょう。
• 開発ドキュメント：開発チームがプロジェクトを継続的に進捗できるよう支援するために設計されています。また、社内開発作業の円滑な進め方を提供し、ステークホルダーへの機能の適切な伝達を保証する必要があります。
• コミュニティ コンテンツ: これには、プロジェクトについて詳しく知りたいコミュニティ メンバーをサポートするために設計された基本的なブログ、ビデオ、外部コンテンツが含まれます。

スタイルガイドラインを用いることで、ドキュメントの全体的な前提が一貫した言語スタイルでユーザーに伝わります。しかし、これらのドキュメントは最終的にはテクニカルライターのチームによって作成されるため、ライティングスタイルは人によって異なるため、チーム間で矛盾が生じる可能性があります。では、どのようにドキュメントを標準化できるのでしょうか？

標準化された文書

ドキュメントの標準化には、様々なアプローチがあります。まず第一に、様々な役割に適した定義済みのテンプレートを作成することです。これらのテンプレートは、新機能のドキュメント化、バグや問題の特定、そして継続的な追加に対応するために変更履歴の更新に使用できます。

Gitベースのワークフローを使用している場合は、ドキュメントを公開するための標準化されたワークフローを開発してみてください。最も標準的なワークフローは、ドキュメントを公開するリポジトリをフォークし、変更をローカルブランチに追加し、変更をプッシュし、リクエストを送信してレビューを依頼するというものです。標準化されたドキュメントの利点の一つは、フィードバックとレビュープロセスの改善につながることです。

フィードバックと自動レビュー

標準化により、ユーザーからのフィードバックを取得し、自動レビューを生成できるようになります。これらのフィードバックは、プロジェクトやドキュメントの改善に活用できます。また、このフィードバックは、共有した情報がユーザーにとって有益かどうかを判断するのにも役立ちます。GitBookのようなドキュメントプラットフォームは、適切なフィードバックサービスを提供しており、ドキュメントの有用性を検証するのに役立ちます。

ドキュメントについては、常に主題専門家（SME）からのフィードバックを求めましょう。SMEには、ステークホルダー、開発者、エンジニア、さらには外部の貢献者も含まれます。また、自動テストやCIを活用して、ドキュメントがスタイルガイドラインに準拠しているかどうかを確認することもできます。

ドキュメントクラウドソーシング

ドキュメントをオープンソース化したい場合、おそらく最適なアプローチはクイックスタートガイドを提供することです。CONTRIBUTING.md ファイルのようにシンプルなもので、基本的にはプロジェクトのセットアップ方法と貢献方法、そして使い方を説明するだけで十分です。

私たちは、各プロジェクトの目的を明確に示す、ユーザー中心のドキュメントを継続的に開発しています。また、新しい貢献者を支援するための学習コースも作成しています。

目的を持って文書を書く

常に目的を念頭に置いて書きましょう。これは最も基本的なライティング戦略の一つであり、特定の文書をどのように書くかではなく、なぜ書くのかを明確に定義します。まず、以下の質問に答えてみましょう。

• このドキュメントの目的は何ですか?
• どのような情報を伝える必要がありますか?
• この後、ユーザーはどのような行動を取ると予想されますか?
• 読者とどのような価値観を共有していますか？
• ドキュメントのスタイルは簡潔で一貫していますか?

一貫したコンテンツ戦略を定義する

一貫したコンテンツ戦略は、ドキュメントとプロジェクトインフラの長期的なビジョンの確立に役立ちます。それは主に以下の2つの側面を中心に展開されます。

• リソース: プロジェクト ドキュメント、ケース スタディ、ホワイト ペーパー、プロジェクト アーキテクチャなど。
• ブランドコンテンツ: ブログや招待投稿、ニュースやコミュニティストーリー、学習コースなど。

すべてのオープンソースプロジェクトには、ユーザーに提供する機能について適切なドキュメントを用意し、最適なソリューションを選択できるようにする必要があります。適切なドキュメントは正しい情報を伝えるだけでなく、他の開発者がプロ​​ジェクトをさらに強化・改善するための貢献を可能にします。一見簡単そうに聞こえますが、ドキュメントは適切に作成されて初めて成功します。そして逆に、プロジェクト自体もドキュメントが正確でなければ成功しません。ですから、プロジェクトの目標やプロセスを決して軽視してはいけません。