ご無沙汰してます。Personium Projectのhideakikondoです。
注）記事は全て個人の見解であり、会社・組織を代表するものではありません。
前回の記事に記載の通り、OSSプロジェクトとして致命的な点「ドキュメントがPoorである」という問題を解消すべく、ドキュメント整備をどうすべきかということに頭を抱えてきました。
今回は、今のところの答えと今後の取り組みについて書こうと思います。
OSSのドキュメントをどう整備していくか、という問題
まずはじめに考えなければならなかったことは、ここでした。
最初は手当たり次第書く、ということをしていたのですが、途中で沸いてきた疑問がありました。
- どんなドキュメントをどういう順番で出していくことが正解なのか
- 今どの程度の進捗で現在地がどこなのか
一般的にオープンソースプロジェクトが、ドキュメントをどういう観点で拡充していくかということに関しては、未だに明確な解が無いと思ってますが、自分で作業をしたり考えた結果、以下のような観点が重要かなと考えています。
- ユーザーストーリー
- 学習曲線
- メンテナビリティ
1は、「誰が、どんなことに困ってドキュメントを探すか」を的確に定義して、それを効果的にサポートするための情報資材を準備していく、ということです。特に、プロジェクトという集団で多くのドキュメントを作成する必要があるので、この定義が曖昧だと完成したドキュメントが意味をなさないということが起こりえます。（過去起こりました）
2は、「読者の理解度に合わせて、説明の流れや形式を工夫する」ということです。その学習曲線に応じて理解のプロセスをデザインすることが理想だと思います。具体的には、技術者でない人は動画で説明する、技術者には具体的なコードを示す、といったことだったりすると思います。
3は、「メンテナンスにかける時間やコストを最小化する」ということです。たいていのプロジェクトは、ドキュメントをはじめとする情報資材を整備する専門の人員を用意することは非常に困難です。解決策はまだ模索していますが、たとえばWebサイトだと「GitHubページを使う」だったり、「markdownで原本をGit管理してHTMLへ自動変換・デプロイする」といったことが考えられます。
この他に、Qiitaのようなオープンな場に下書き段階から公開していくということも、オープンソースプロジェクトが今後どういう整備方針なのかを示すという点において、重要だと考えました。
ターゲットと整備すべきドキュメントを決める
上記の3つのルールをベースに、
「どんな人が」
「どんなことをするため」
「どういうものを用意する」
ということを定義して、リストを起こしました。それが以下になります。
| # | ターゲットユーザー 英名 |
行動目的（何がしたい） | ドキュメントの候補 | 想定するスキル別分類 | スキル範囲、言語 | ドキュメント・実装 |
|---|---|---|---|---|---|---|
| 1 | 一般ユーザ End User |
とりあえず知りたい、理解したい | 対象者ごとの文書 （企画系、技術者系、アプリ利用者系など） |
A:非技術者 B:技術企画者、マネジメント |
なし（企画系） あり（技術系） |
Webページ Personium仕様共通説明（すぐ必要） |
| 2 | Personiumアプリ開発者 App Developer |
PersoniumのAPIを使用して、アプリを開発したい | アプリ開発ガイドREST API リファレンス（BoxAPI） | C:Webフロントエンドエンジニア G:ネイティブアプリエンジニア |
HTMLアプリ（Javascript） ネイティブアプリ（Android/iOS/Win） |
APIリファレンス アプリ開発ガイド（執筆予定） サンプル実装 |
| 3 | Personium Cell 管理クライアント開発者 Cell-Client (Home-App) Developer |
PersoniumのHomeアプリを開発したい | Homeアプリ開発ガイドREST API リファレンス（CellAPI） | C:Webフロントエンドエンジニア G:ネイティブアプリエンジニア |
HTMLアプリ（Javascript） ネイティブアプリ（Android/iOS/Win） |
APIリファレンス Homeアプリ実装例 |
| 4 | Personiumユニット管理者 Unit Administrator |
自社サービスを提供するため、構築済みのPersoniumユニットを管理したい 自社のPDSアプリをユーザーに利用してもらいたい |
ユニット管理ガイド（Cell管理マニュアル）UnitManager/PCUI REST API リファレンス（UnitAPI） |
D:システム管理者 | HTTP REST API(Curl) （サーバログインはしない） |
APIリファレンス |
| 5 | Personiumサーバソフトウェア運用者 Server (Infra) Operator |
OSSソフトウェアを利用して、所有環境でPDSサービスを運用したい | 環境構築ガイド、Ansible、Heat Templete ミドルウェア一覧 運用・セキュリティポリシーの参考情報（XXしたほうがよいの類） |
E:インフラエンジニア | サーバ運用（Linuxなど）インフラ構築スクリプト言語（Shell, Ansible） |
Ansible Heat テンプレート 構築ガイド |
| 6 | Personiumサーバプラグイン開発者 Plugin Developer |
自社の既存環境と最適化するなどのため、サーバ機能を拡張したい そのために、プラグイン・エンジンエクステンションを開発して利用したい |
Core Plugin開発ガイド Engine Extension開発ガイド |
F:サーバサイドエンジニア | Java LinuxServer |
Personiumプラグイン開発ガイド コントリビューターガイド |
| 7 | Personiumサーバ開発者 Software Developer |
PersoniumのOSSの機能を開発したい OSSにコミットしたい |
Personium本体開発ガイド コントリビューターガイド |
F:サーバサイドエンジニア | Java LinuxServer |
Personium本体開発ガイド コントリビューターガイド |
これをまとめたことによって、いくつかのメリットがあることに気付きました。
- これから整備すべきドキュメントを俯瞰できた（ゴールと進捗が分かりやすくなった）
- ターゲットが定義されて整備するための共通認識ができた
- 不足しているコンテンツが何であるか、どの順番で整備していくかを議論しやすくなった
- プロジェクトのスタンスをオープンにすることができた（この記事で）
などです。
現状の整備段階の中では、ほとんどのドキュメントができていないなあということがはっきりしたので、あとはどんどん書いていくだけ（泣）という状況になっています。
OSSなので執筆してくれる方も募集してます！(｀･ω･´)
さあドキュメントを整備しよう
整備計画が立ったところで、はじめの取っ掛かりとしては
アプリ開発ガイド
を
Qiitaで順次執筆・公開しよう
と考えています。
理由は、
- アプリがPersoniumエコシステムを形成するためのキーになる
、そして、
- Qiitaで公開することで仕様に関する議論を巻き起こして最適解を出したい
からです。
これを読んで、アプリを作ってくださる方や仕様へのご意見を下さる方が現れることを期待しています！
とりあえずの「アプリ開発ガイド：目次」
応用編
a. サーバサイドJavascript（Engine service)の利用
b. engine extensionを使って、Engineの機能を拡張する
c. Homeアプリを開発する
d. アプリマーケットで公開する
・公式（？）マーケットを使用する場合
・Webサーバを使用する場合
コンプリートまで長い道のりですが地道に頑張ります…
意気込み
積年の課題だったドキュメント整備が、この記事をもってやっとスタート地点に立てました！
私個人としては、ドキュメントをQiitaに書いていくという取り組みを試してみたかったので、まずは最初の執筆ができて良かったです。
ここに書いていったことが、（多言語対応ののちに、、）Personiumプロジェクトの公式ドキュメントに昇格することになりますので、応援・いいねのほど宜しくお願い致します！
では、スマイルスマイル～(∩´∀｀)∩