良い文書を作成するのは難しいことですが、効果的なコミュニケーションには欠かせません。このフレームワークに従って、適切な文書を作成し、適切な人々と共有しましょう。
成功した持続可能なプロジェクトと、跡形もなく消えていくプロジェクトを区別するものは何でしょうか？答えは、コミュニティです。コミュニティこそがオープンソースプロジェクトの原動力であり、ドキュメンテーションはそのコミュニティ構築の礎のひとつです。言い換えれば、ドキュメンテーションには、ドキュメンテーションそのもの以上のものがあるということです。
良いドキュメントを作るのは難しいものです。ユーザーがドキュメントを読みたがらないのは、見つけにくかったり、すぐに古くなってしまったり、長かったり、包括的でなかったりするからです。
開発チームがドキュメントを書かないのは、「私にとって自明であれば、誰にとっても自明である」という罠に陥るからです。開発チームがドキュメントを書かないのは、プロジェクトの開発が忙しすぎるからです。要求事項の変化が速すぎるか、開発スピードが遅すぎるかのどちらかです。
しかし、優れたドキュメントは、チームとプロジェクト間の最良のコミュニケーションツールであることに変わりはありません。プロジェクトが時間とともに大きくなる傾向があることを考えると、これは特に重要です。
ドキュメンテーションは、チームや企業内で唯一の真実となり得ます。これは、共通の目標に向かって人々を調整し、人々が異なるプロジェクトに移動しても知識を保持する上で重要です。
では、プロジェクトのために適切な文書を書き、それを適切な人々と共有するためには何が必要でしょうか？
成功するコミュニティ・ドキュメンテーションとは？
コミュニティ・ドキュメンテーションで成功するには、次のことが必要です：
- プランニング・パス
- 明確でシンプルに
- 特定の状況にパスウェイを適応させる柔軟性
- バージョン管理
柔軟性は混乱を意味しません。多くのプロジェクトが成功するのは、うまく組織化されているからです。
ジェームス・クリアは、"目標があるレベルまで上げるのではなく、システム全体があるレベルまで下げるのだ "と書いています。成功するのに十分なレベルになるように、プロセスを整理してください。
デザインプロセス
ドキュメンテーションはそれ自体がプロジェクトです。まるでコードを書くように、ドキュメントを書くことができます。実際、ドキュメンテーションは製品になり得ますし、それはとても価値のあるものです。
つまり、ソフトウェア開発と同じプロセスで、分析、要件取得、設計、実装、保守を行うことができ、ドキュメントをプロセスとして扱うことができます。
プロセスを設計する際には、さまざまな視点から考えることが重要です。すべての文書がすべての人に通用するわけではありません。
ほとんどのユーザーは、プロジェクトの概要を説明する文書が必要なだけで、API文書は開発者や上級ユーザーのためのものです。
開発者は、ライブラリや関数のドキュメントについて知る必要があります。ユーザーは、例やハウツーガイド、プロジェクトが他のソフトウェアとどのように組み合わされているかについてのアーキテクチャの概要を見る必要があります。
つまり、どのようなプロセスを作るにしても、何が必要かを判断しなければなりません：
- フォーカスグループ： 開発者、インテグレーター、管理者、ユーザー、営業、オペレーション、経営幹部など。
- 専門知識レベル： 初心者、中級者、上級者を考慮する必要があります。
- 詳細レベル： ハイレベルな概要と技術的な詳細の両方が必要。
- 経路と入口： 人々が文書をどのように見つけ、どのように利用するか
これらの質問について考えることは、文書を通して伝えたい情報を構成するのに役立ちます。何が文書に含まれなければならないか、明確な指標を定義します。
ここでは、ドキュメントを中心にプロセスを構築する方法を説明します。
コーディング規約
コードそのものが理にかなっていること。クラス名やファイル名など、ドキュメントを適切に表現する必要があります。次のようなことを考えて、共通のコーディング標準と自己注釈付きのコーディングプロセスを作りましょう：
- 変数の命名規則
- クラスと関数の命名スキームを使用して、名前を理解しやすくします。
- 深い巣を避けるか、 まったく巣を作らないか
- コードをコピー＆ペーストするだけではいけません
- 長いメソッドは使用しないでください。
- ファントムナンバーの使用は避けてください
- 抽出されたメソッド、変数などの使用。
- 意味のあるディレクトリ構造、モジュール、パッケージ、ファイル名の使用
開発中のテスト
テストは、コードがどのように動くべきかについてだけではありません。APIや関数、メソッドなどがどのように使われるかということでもあります。よく書かれたテストは、基本的なユースケースやエッジケースを明らかにすることができます。コード開発におけるテストケースの作成に焦点を当てた テスト駆動開発という プラクティスもあります。
バージョン管理
バージョン管理は、変更のロジックを追跡するのに役立ちます。なぜその変更が行われたのかという疑問に答えるのに役立ちます。
ドキュメンテーションのプロセスがより魅力的であればあるほど、より多くの人々がそれに参加し、創造性と楽しさを加えてくれるでしょう。ドキュメンテーションの読みやすさについては、次のような点を考慮する必要があります：
- ソフトウェアコード規約
- チャートとグラフ
- 思考マップ
- コンセプトマップ
- インフォグラフィック
- 写真
さまざまなコミュニケーション・スタイルを用いることで、文書への関わり方を増やすことができます。これは誤解を防ぎ、さまざまな学習スタイルによる学習に貢献します。
文書作成に使用されるソフトウェア・ツールには、次のようなものがあります：
- Javadoc、Doxygen、JsDocなど： 多くの言語には、コード内の主要な機能をキャプチャするのに役立つ自動ドキュメントツールがあります。
- WebフックとCI/CDエンジン： 継続的なドキュメントのリリースを可能にします。
- Restructured Text、Markdown、Asciidoc： プレーンテキストファイルから美しく有用な文書を作成するためのファイルフォーマットと処理エンジンです。
- ReadTheDocs: は、公開Gitリポジトリにリンクできるドキュメントホスティングホストです。
- Draw.io、LibreOffice Draw、Dia: チャート、グラフ、マインドマップ、ロードマップ、計画、標準、指標などを作成できます。
- Peek、Asciinema： ターミナルコマンド操作の記録
- VokoscreenNG： 画面とマウスクリック操作の記録
ドキュメンテーションは重要です。
ドキュメンテーションを書くプロセスと手順は、プロジェクトそのものと同じくらい重要です。最も重要なのは、プロジェクトのメッセージとプロジェクトの創造をよりエキサイティングに伝えることです。
プロジェクトやプロセスに素早くアクセスし、すべての仕組みを理解することは、文書化の重要な特徴です。これは、従業員のモチベーションを維持するのに役立ちます。チーム内で「言語」を構築することで、プロセスを合理化し、何をすべきかをより明確に理解することができます。
ドキュメンテーションは、価値を伝えること、すなわち、チームメンバーやアプリケーションのユーザの言動を通してであれ、何かを示すことを意図しています。
プロセスを連続体として捉え、その中でコミュニケーション、プロセス、ドキュメンテーションを統合することが重要です。
ドキュメンテーションはコミュニケーションの手段です。
