ここ1週間ほどドキュメントを読んだり実機を触ったりしたうえで感じたことを書き記しておきます。
企業の製品やマーケティング活動にあれこれケチをつけて「こうすればいいのに」「わかっていない」と吠えるのは一番みっともないユーザーと相場が決まっています。が、ほかには私にできることもないようですので。
リファレンス・マニュアルとユーザーズ・ガイドを分けよう
常々言っていることですが、コンピュータ・プログラムのマニュアルはリファレンス・マニュアルとユーザーズ・ガイドに分けるべきです。これはパッケージソフトやSaaSといったユーザー向けソフトだけではなく、評価ボードを含めた開発ツールにも言えることです。
ここでリファレンス・マニュアルとは、製品に関する説明を製品の体系にそってまとめた本です。例えばSpresenseであればハードとソフトの大分類にわけられ、ソフトは開発ツールと実行ソフトにわけられ、実行ソフトはOSとミドルウェアとアプリケーションにわけられます。このような木構造に分類して知識を整理するのがリファレンス・マニュアルです。リファレンス・マニュアルは百科事典的なものとなります。リファレンス・マニュアルの良い所は、すべての知識がそこに書いてある点です。一方で悪いところは、体系を知らなければ必要な知識に辿りつけないことです。
ユーザーズ・マニュアルとは、ユーザーが作業をする手順にそって知識がまとめられた本です。例えばSpresenseであれば、箱を開けたあとのボードの組み立て、電源との接続、開発ツールのダウンロードと設定、ファームウェアの取得とカキコmい、最初のプログラムのビルド、最初のプログラムのかき込みと実行などと言った流れです。ユーザーズ・マニュアルは作業マニュアルのようなものとなります。ユーザーズマニュアルの良い所は、最初から読みながら作業をすれば必要な知識が必要なときに目の前に現れることです。一方で悪いところは、すべての知識を網羅しているわけではないこと、必要な知識がどこにあるか最初から読まないとわからないことです。
ユーザー向けのマニュアルは上記の2つが補完しあうように書くべきです。最初はユーザーズ・マニュアルから入り、やがてはリファレンス・マニュアルだけで作業できるようになることが理想です。ですのでユーザーズ・マニュアルには要所要所にリファレンス・マニュアルのどこを読めばより詳しく学べるか書いていなければなりません。
長いストーリーではなく、小さな作業についてやりたいことを集めた本もあり、それらはクック・ブックと呼ばれます。クック・ブックは本質的にはユーザーズ・マニュアルに近いものです。
ユーザーズ・マニュアルをまとめたほうがいい
Spresenseについては、まず独立したユーザーズマニュアルを用意すべきです。
Spresenseのデベロッパー・サイトを見ると、Spresense SDKでの開発ページに、みっつのサブメニューがあります。
- Spresense ハードウェアの設定
- Spresense SDKチュートリアル
- Spresense SDKデベロッパーズガイド
このうち、ハードウェアの設定とチュートリアルはひとつにまとめるべきです。この2つは知っておくべき最低限の知識と作業手順を記したものですので、デベロッパーズガイドと並べて置く理由がありません。SDKチュートリアルにまとめて方がいいでしょう。また、昨日も書きましたが、ハードウェアの設定と同じものが別項目にも独立していますが、混乱するのでそちらは削除したほうがいいでしょう。Arduinoの方は見ていませんが、そちらもチュートリアルを作りやはりハードウェアの設定としてこちらのコピーをおいておくとよいです。ユーザーからするとSpresense SDKのチュートリアルとArduino IDEのチュートリアルにそれぞれ同じハードウェア設定情報があっても混乱はしません。しかし、独立したハードウェア解説に全く同じ内容のものがあると混乱してしまいます。最後まで読まなければ同じものかわかりませんし、Spresense SDKだけ使いたい自分に必要なものかどうかも判断できません。
Spresense SDK チュートリアルに追加の例題を入れるべき
チュートリアルではprintf()によるHelloの出力プログラムのビルドと実行方法が解説されています。しかし、その先が全く書かれていません。
昨日この延長でLED点滅プログラムを書いたのですが、何をインクルードすればいいのかわからず、ドキュメントとサンプルプログラムを延々と漁るはめになりました（結局システム・コマンドのソースを読んでやっとわかった）。
LEDチカチカは頻繁に馬鹿にされますが、ある開発ツール体型を説明する際に次のような点を簡潔に説明できる利点があります。
- ハードウェア資源にどうアクセスするかを端的に説明することができる。
- 時間の抽象化に関して、APIを提示することでユーザーに入り口をしめすことができる。
最初のHelloに肉付けする形でLED点滅をするよう持っていけば、ユーザーにとって非常に良いチュートリアルになります。
I2Cへのアクセスの例題
I2Cに関してもひとつサンプルをチュートリアルに入れておくべきです。
Spresense SDKはNuttXの上に構築されていますが、NuttXは日本では馴染みの薄い、つまり情報の少ないOSです。このOSではI2Cのような基本デバイスはOSの管理下にあります。ですので、開発者はどのようにアクセススべきかネット中を駈けずり回って調べなければなりません。
Contaシールドと適当なセンサーを使った例題を用意して解説すれば、ユーザーにとってNuttXへの良い入り口になります。
コンフィギュレータの解説
チュートリアルの締めはコンフィギュレータにすべきです。
コンフィギュレータについてはSpresense SDK チュートリアルの中でdefconfigによるコンフィギュレーションが触れられている程度です。それ以上についてはSpresense SDK デベロッパーズガイドを調べなければなりません。
コンフィギュレータはSpresenseのソフトウェアと密接につながっています。SpresenseはOS、ミドルウェア群、アプリケーション群をひとつのパッケージとして扱っており、コンフィギュレータはこのパッケージ全体を管理しています。それはどちらかというとLinuxのディストリビューションのコンフィギュレーションに似ています。
すべてのデベロッパー、特にArduionoやmbedのような小型プラットホームの開発者にこういった知識を期待するのは無理があります。「そうではなくて、Raspberry Piが敵だ」という声もあるかもしれませんが、コンフィギュレータの解説を端折って良い理由としてはやや説得力不足です。
多少面倒でも、Spresenseのソフトの構造とコンフィギュレータについてチュートリアルできちんと説明したほうがいいでしょう。
オーディオとGNSSのチュートリアルを別途作るべき
SpresenseはオーディオとGNSSが売りなので、この2つのチュートリアルを作るだけの理由は十分にあります。
特に、Spresense SDKデベロッパーズガイドは、ユーザーズガイドとして読む分には、全く作業の助けにならず、リファレンス・マニュアルとして読むには内容が散漫すぎます。そして、Spresense API referenceは骨抜き状態です。
仮にSpresense API referenceが今後充実するとしても、様々な応用とスケーラビリティを考えて作りこんであるオーディオ・ミドルウェアについては、APIリファレンスと初めて作業にとりかかる人のギャップを埋める物が必要です。現状のサンプルはほとんどコメントがなく「動くよ」程度のものですが、まずはこれらのサンプルに「なぜこのAPIを読んでいるのか」「なぜこの関数を定義しなければならないのか」といったコメントを追加するところから始め、ユーザーのエフェクトをプレイヤーに追加するといったチュートリアルを設けたほうがいいでしょう。
Spresense SDKデベロッパーズガイドが中途はんば
このドキュメントをリファレンスにしたいのか、チュートリアルにしたいのかはっきりすべきです。
ページタイトルがSpresense SDK 開発ガイドで、ページ名がnuttx-developer-guideであることに迷いというかこれまでの経緯を垣間見るようですが、リファレンスとしてもユーザーズガイドとしても中途半端であることはすでに述べたとおりです。
まとめ
思いついたことを書き出してみました。Spresense SDK自身は資料を読めば読むほど「すごいものを公開したな」という気分になります。これは適当に作った評価システムではなく、明らかに数百万台も製造される製品で使うために構築された、ソニーの社内用開発プラットホームです。
NuttXやコンフィギュレータの解説はソニーが行うべきものなのか？という声もあるでしょう。しかし、このまま「とっつきにくな」と放置されるのも不本意だろうと思われるので、なんとか頑張って敷居を下げてほしいものです。