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

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

・優れた文章はオープンソースソフトウェアの成功に多大な貢献をする
・しかしながら文章はソフトウェアのオマケ扱いにされ後回しにされがちである
・どのようにすれば良いドキュメンテーションを書く事ができるようになるのか？

２．ソフトウェア開発におけるドキュメントの重要性

開発者がオープンソースソフトウェアを使用し、選択し、貢献するとき、良くできた文章があるか否かは、肯定的な反応になるか否定的な反応になるかの違いを生み出します。

実際、2017年のGitHubの調査では、「不完全で混乱した文書」がオープンソースソフトウェアの主な苦情であるとTechRepublicは書いています。「オープンソースについての主要な不満は何かと開発者に尋ねると、ドキュメントについての不満が最も多く、最も多様です」

Googleのテクニカルライターは、Google Cloudのオープンソースプロジェクトを手始めに、この問題に取り組んでいます。私達は自ら学んだ事を分かち合い、この短いガイドを出発点として提供することにエキサイトしています。

オープンソースソフトウェアのドキュメント
オープンソースソフトウェアの効果的なドキュメンテーションを提供することで、強力で包括的なコミュニティを構築し、製品の使用を増やすことができます。

オープンソースプロジェクトの共同開発を促進する要因が、文書作成時にも肯定的な結果をもたらす可能性があります。オープンソースソフトウェアは、良い文書を作成するためのユニークな方法を提供しています。

ソフトウェアがオープンソースの場合、ユーザーは貢献者とみなされ、ソースコードとドキュメントにアクセスできます。ユーザは、機能追加やコードの修正、バグの報告、ドキュメントの更新をする事を奨励されます。貢献者を増やすことで、ソフトウェアとドキュメントの品質を高めることができるのです。

ソフトウェアの採用を加速する最善の方法は、その利点を説明し、その使用方法を示すことです。タイムリーで、効果的で、正確なコンテンツの利点は多数あります。

ドキュメントがあれば、十分な時間と費用を節約できるため、
・包括的なコミュニティを作成するのに役立ちます
・より良いソフトウェア作りに集中する事ができます
・製品の採用を促進します
・製品のメンテナンスコストを削減します
・ユーザの学習曲線を減少させます
・ユーザーを幸せにできます
・ユーザーインターフェイスを改善します

ドキュメンテーションが不十分な場合は、逆のことが起こる可能性があります。誤った、古い、または不足しているドキュメントは、

・時間を無題にします
・エラーの原因とデータの破壊に繋がります
・顧客を切り捨てます
・サポートコストが増加します
・製品の寿命を短くします

効果的な文書を提供することはなぜ難しいのでしょうか？
有益なドキュメントは、執筆に時間がかかり、ソフトウェアが更新されるとドキュメントも更新する必要があります。インストール方法が変更されましたか？パフォーマンスを上げるために設定を変更する良い方法がありますか？ユーザーインターフェイスが変更されましたか？新しい機能が導入されましたか？上記のようなアップデートがソフトウェアに発生する度に、新規および既存の顧客に説明する必要があります。

ファイルに単語を追加して、そのファイルを「ドキュメント」と呼ぶだけでは不十分です。

あなたは5年前以上メンテされていないドキュメントを読んでみた事が過去に何回ありますか？検討してたオープンソースの採用を止め、別の解決策を見つけるのにどのくらいの時間がかかりましたか？(そんなに長くないですよね？）古いドキュメントを読む事は、維持管理されていない山道をハイキングするようなものです。邪魔な枝、毒のツタ、そして迷子、あなたが無傷で戻れる可能性は低いでしょう。

一見すると、文書を書くことはオマケのように見えるかもしれません。しかし、開発者はその製品の特徴と目的を知っていて当然です。そして、あなたの顧客は、あなたが知っていること、またはビジネス上の課題に対処するためにあなたが知っている事を使ってどのように解決できるのかを知りません。
時間はお金です。

モメンタム(慣性)は大変重要です。新機能の実装、コード内のバグ修正、ドキュメントの作成と更新、これらを一連のリズムで行う事に慣れれば、それは貴方を成功に導びきます。

包括的なオープンソースコミュニティを作り上げる
前述のGitHubの調査では、回答者の95％が男性でしたが、良くできた文書のメリットが示唆されています。良くできたドキュメントは、
・包括的にコミュニティに貢献することができます
・一般的に考えられているより大きな価値があります。

プロジェクトのプロセスについて説明し、コードの実行方法を解説している良くできたドキュメンテーションは、オープンソースコミュニティで過小評価されているグループ、例えば女性達にとっても有用です。

有用でない文書が出来上がる要因
以下ような考えは、ほとんどの場合、ドキュメントの品質を損なうことになります。

・オープンソースソフトウェアだけで十分だと考え
・仕様書は教科書のようであれば良いという考え
・カジュアルな推敲されていない投稿で十分であるという考え
・予定外および不特定なソフトウェアの更新が受け入れられるという考え
・文章のスタイルに関するガイドラインが最低限のものしかない

ドキュメンテーションを克服しましょう！
以下のベストプラクティスを念頭に、有益でタイムリーなドキュメントを提供してください。

（優れたオープンソース文書の作成方法(2/2)に続きます）

３．優れたオープンソース文書の作成方法(1/2)関連リンク

１）opensource.googleblog.com
Building great open source documentation