優れたオープンソース文書の作成方法(2/2)

１．優れたオープンソース文書の作成方法(2/2)まとめ

・用語の定義やひな型や投稿基準を作り関係者が効率的に執筆できるようにする
・ソフトウェアの変更がユーザに行動の変化を強いる時に文書も変更する
・定期的な見直しを行い現状に合わない文書がないかチェックをする

２．ドキュメントを更新するべきタイミング

以下、opensource.googleblog.comより「Building great open source documentation」、元記事は2018年10月15日、Janet Daviesさんによる投稿です。

ドキュメントのベストプラクティスとは？

(1)共通の用語を特定する

用語の定義と使用方法を定めましょう。ガイドと製品内で同じ用語を使用してください。製品開発の初期段階にライターを関与させることで、ユーザーインターフェイス、ガイド、トレーニングテキストの間に自然な相乗効果が生まれる可能性があります。明確な用語の定義とドキュメントの一貫した使用法により、コミュニティが共通の言語を話せるように導く事ができます。その結果、製品のエコシステムのすべての人がより効果的にコミュニケーションを取ることができます。

(2)寄稿のガイドラインを示す

Opensource.comは、寄稿のガイドラインがなぜ重要であるかを正確に説明しています。Kubernetesがユーザーが寄稿できるドキュメントの種類とその作成方法について説明している理由を考えてみてください。

(3)ドキュメントのひな型を作成する

投稿者が一貫した形式で詳細を記述できるように、ドキュメントのひな型を用意してください。例えば、次のような共通な章構成にし全体を把握しやすくすることを検討してください。

・概要
・前提条件
・ステップ毎の手順
・次にすべき事

(4)新しい機能と更新された機能を文書化する

機能が追加または更新された時、その機能が文書化されているかどうかを尋ねてください。貴方は重要な情報をドキュメントに含まめるようにガイドラインを示す事もできます。最初の頃は、開発プロセスの早い段階で説明用ドキュメントを書くことを煩雑に思う人もいるかもしれません。しかし、ソフトウェアのドキュメントを作る事は、ソフトウェアをテストする事と同様です。誰もが本当はやりたくなくとも、その効果はあらゆる事にプラスの影響を及ぼします。十分な試験と指導は、ドキュメントの品質とモメンタムに良いものです。

オープンソースソフトウェアのコードレビュー担当者やメンテナンス担当者は権力を持っています。コードレビュー担当者は、文書化が十分になるまで承認を保留することができます（また、保留する必要があります）。

すべての変更がドキュメントの更新を必要とするわけではありません。良い原則は次のとおりです。

プロジェクトの更新でユーザーが行動を変更する必要がある場合は、ドキュメントの更新が必要になるでしょう。

そうでない場合は、貴方の顧客は貴方が一生懸命作業して実装した新機能をどのようにして見つけるのでしょうか？言い換えれば、変更がテストを必要としないのであれば、ドキュメントの変更も必要ない可能性があります。

賢明に判断してください。たとえば、コードのリファクタリングや実験的な機能を実装した事は文書化する必要はありません。

いつものように、できるだけこのドキュメント化のプロセスを簡素化し、自動化してください。Googleでは事前確認チェックによりドキュメントの更新の要不要を確認する事ができます。事前確認では書式についてもチェックすることで多くの作業を省く事ができます。また、ファイルの所有者はレビューなしで変更を確定することができます。

もし、あなたのチームがこのドキュメント化に関する作業を嫌うなら、プロジェクトに関するシンプルな文書とは自らの頭の中にある情報を共有することであり、ドキュメント化を行っておけば、多くの人が後であなたの手を煩わせず学ぶ事が出来るという事実を思い出させてください。

ドキュメントの更新は一般的に面倒ではありません！ドキュメントのサイズは、プルリクエスト(PR)のサイズに応じて変わります。PRに1000行のコードが含まれている場合は、数百行の文書を書く必要があります。PRに1行の変更が含まれている場合は、1つまたは2つの単語を変更する必要があります。

最後に、ドキュメントは完璧である必要はありませんが、使用に耐えうるものでなければならない事に注意してください。最も重要なことは、必要な情報が明確に伝達されていることです。