ククログ

株式会社クリアコード > ククログ > ノータブルフィードバック1 - 導入時のつまずきを減らす報告

ノータブルフィードバック1 - 導入時のつまずきを減らす報告

結城です。

最近このブログで、「よいコミット・よいコードの実例」を紹介することを通じて他の人のコードを読むことを奨励していく、ノータブルコードというコーナーが始まりました。それに便乗する形で、「OSSへのよいフィードバックの実例」の紹介を通じて身近なところからのOSSへのフィードバックを奨励していく記事を掲載していきたいと思います。

1回目は、当社の堀本さんがOCamlというプログラミング言語に対して行ったフィードバックをご紹介します。

フィードバックの経緯

当初、OCamlのWindowsでのインストール手順は、必要なコマンドを以下の順で実行するよう書かれていました。

opam init
eval `opam env`
opam switch create 4.06.1
eval `opam env`
which ocaml
ocaml --version

この最後のocaml --versionは、実行結果としてocamlコマンドのバージョン番号が表示されることをもって、OCamlのインストールに成功したことを確認するためのものです。

しかしながら実際には、これを実行すると「--versionは未知のオプションである」というエラーが表示されます。実は、正しいオプションは-version(ハイフンが1つ)で、インストール手順の記述が誤っていたわけです。

堀本さんはこれを受けて、誤記を訂正するプルリクエストとして以下のようなフィードバックを行いました

■タイトル install: fix a typo ≪インストール:誤記の修正≫ ■本文 Dear developers. ≪開発者の皆さん、こんにちは。≫ In my environment, --version is unknown option. ≪私の環境では、--versionは未知のオプションと表示されます。≫ Probably, -version is valid option for ocaml command. ≪おそらく、-versionがocamlコマンドの正しいオプションです。≫

ほとんどの人は気にしないで使っていたのだと思われますが、いきなりエラーに見舞われると、初学者ほど戸惑うものです。

このプルリクエストは無事にマージされ、現在はそのようなつまずきは起こらなくなっています。

注目したい点

ここで注目して欲しいのは、フィードバックの結果、ソフトウェアを使い始める際に特別な注意が必要ない状態になったということです。

ブログなどでソフトウェアを紹介するとき、「このソフトウェアを使う時はこのような点に注意が必要です」といったノウハウを添えて紹介する記事はよくあります。ですが、冷静に考えてみれば、ソフトウェアを使い始めた人が高確率で戸惑うであろう注意点は、注意するべき点と言うよりも不具合不備と言った方が適切です。

ノウハウの言語化・文書化は有意義ですが、OSSに関わりたいと考えている人は、ぜひそこから一歩先に考えを進めてみてください。 「使う時に特別な注意が必要ないのが一番いい」、これはどんな場合にも言える事です 。この考えを持っていれば、「些細な戸惑い」や「使用上の注意点」はおのずと「改善した方がよい点」に見えてくるでしょう。

まとめ

ノータブルフィードバックの1回目として、OCamlのインストール手順に対して行われたフィードバックをご紹介しました。

ここで紹介したような「身近なところで遭遇したつまずきをOSS開発プロジェクトにフィードバックする」ということをテーマに、まだOSSにフィードバックをしたことがない人の背中を押す解説書 「これでできる! はじめてのOSSフィードバックガイド ~ #駆け出しエンジニアと繋がりたい と言ってた私が野生のつよいエンジニアとつながるのに必要だったこと~」をリリースします。本記事の内容は、この本からの抜粋となっています。 (表紙)

「これでできる! はじめてのOSSフィードバックガイド」は、今週末開催されるはずだった技術書典8というイベントで同人誌として頒布する予定……でしたが、技術書典8の中止により機会が流れてしまいました。

しかし執筆自体は完了しているため、ひとまず本来の開催予定日だった2月29日より、EPUB/PDF形式の電子書籍のダウンロード販売を開始したいと思います。販売チャンネルは、現時点では結城が個人的に運営しているBOOTHを予定しています。紙媒体版についても、同人誌書店での委託・通販や、今後「技術書同人誌博覧会」や、クリアコード関係者が参加する技術イベントなどに持ち込ませて頂いて、細々と頒布していければと考えていますので、お手元に置いておきたいという方はご期待下さい。