Dはオープンソースの生命線
コードが心臓なら、医師は声である
どうした、オタクたち？現実を見よう：コードがオープンソースソフトウェアの心臓であるなら、ドキュメンテーションは声だ。それは、あなたのプロジェクトが世界に語りかける方法なのだ。
そしてここに厳しい真実がある。私は、誰もその使い方を理解できなかったために、素晴らしいプロジェクトがつるの上で死んでいくのを見てきた。ドキュメントがなければ、あなたのコードはただの...ノイズだ。
何がドキュメンテーションを偉大にするのか？
優れたドキュメンテーションとは、画一的なものではありません。システムなのだ。最低限必要なのは
- ユーザーガイド→ 新人をゼロから働かせるオンボーディング・エクスペリエンス。
- APIドキュメント→ あなたのプロジェクトを統合したい開発者のためのライフライン。
- 貢献ガイド→ コラボレーションを促進するコミュニティのプレイブック。
これがなければ、あなたのプロジェクトは、前面に絵のないパズルの箱を人に渡すようなものだ。
医師が採用を左右する理由
想像してみてほしい：あなたは、すべての問題を解決できるオープンソースのツールを発見した。あなたは興奮する。インストールする。すると...音がしない。説明書も例題もなく、ただ "幸運を祈る "と書かれたREADMEがあるだけだ。
あなたは跳ねる。誰もがそうする。
Reactや他のオープンソースの重鎮を見てみよう。彼らのドキュメントはコードと同じくらい洗練されている。これは偶然ではない。明確なドキュメントはユーザーを助けるだけでなく、支持者を生み出す。開発者が壁にぶつかることなく、あなたのライブラリをプラグインできるようになれば、彼らはその言葉を広める。
難しい部分ドキュメントの作成と更新
ああ、ドキュメントを書くのは大変だ。必要なのは
- 専門用語を使わない明快さ
- 伝えるだけでなく、示す例
- 論理的な構成により、答えを素早く見つけることができる
しかし、一番難しいのは？ドキュメントを更新し続けること。古くなったドキュメントは、まったくないよりも悪い。それは、3年前に閉店した企業にあなたを送るGPSを使っているようなものだ。イライラする。
ドキュメントをスキップしてプロジェクトを沈める
ドキュメンテーションは、開発者の集まりであなたのクールなポイントを獲得することはありません。しかし、それがなければ流砂の上に建物を建てることになる。ドキュメントこそが、他のすべての土台なのだ。
だから書く。それを維持する。磨け。コードを生かしたいのであれば、ドキュメントは語らなければならないのだから。
次の記事Eはエンド・オブ・ライフ
次回のOSSのABCでは、「End of Life」（エンド・オブ・ライフ）についてお話しします。
それまでは？コードをクリーンに保ち、ドキュメントをさらにクリーンに保ちましょう。
