2017年7月30日日曜日

ARM-Cortex-M0などの小規模なマイコンでも簡単にシリアル入出力機能を実現するMicroShellのウェブサイトを少しだけ修正した話

ARM Cortex-M0などの小規模なマイコンでも簡単にシリアル入出力機能を実現するMicroShellのウェブサイトを少しだけ修正しました。

修正したのはAPIのページで、以前は定義や関数がズラズラと並んでいるだけのページでした。サイトを構築する際、このAPIページを眺めた後にExampleページを御覧頂く事を考えていましたが、実際にAPIページを見るだけで嫌になりそうです。というのも、読み手からして見れば早く理解して使いたいのに、何の説明もないAPIページを見させられたのではたまったものではありません。かと言って、唐突に自分に関係があるのかわからない具体的なプラットフォームに対するサンプルを提示するのも考え物です。


特に、実際のサンプルでは、複数のモジュールを組み合わせて実際のアプリケーションに近い例を見せていたため、どのAPIが必須なのか、どのモジュールで何を提供しようとしているのかが非常に不明瞭でした。

これらの振り返りをふまえ、新しいAPIページでは以下の対応をしました。

  • 提示しているAPIが必ず必要なものなのか、それとも選択的に使用すれば良いものなのかわかるように[Core]と[Optional]という表記を追加した。
  • 単にモジュール名称を提示するのではなく、一体何を提供しようとしているのかわかる説明をモジュール名称の前に追加した。
  • かなり短いサンプルコードを対象APIのみを使って記述した。

ということで、少しだけ見やすくなったMicroShellのAPIページを是非ご覧頂き、興味があれば色々なマイコンの入力系統にお使い下さい。