by shigemk2

当面は技術的なことしか書かない

OSSドキュメンテーション勉強会に行って、LTした #kbkz_tech

ドワンゴ主催の、歌舞伎座.tech#14「OSSドキュメンテーション勉強会」に行ってきて、LTしました。

こちらは資料です。ひたすらドキュメントに貢献し続けた話をしました。

以下、感想というか雑感を雑に書きます。

あんまり準備できなかったこと

本来なら1週間前には資料が出来ていて、前日までには1回は通しで練習して、発表にかかった時間を確認してスライドを削ったり増やしたりする作業をやるのですが、仕事が忙しいのと、休日もfish-shellにプルリク投げたりしていたので、あんまり時間がありませんでした。

LTも5分なのか10分なのかイマイチよく分からず、当日も尺余りで発表時間がどんどん前倒しになっていくので時間が余ったので10分どころか30分かけてお話しても良かったのですが、実際にかかった時間はだいたい7分30秒くらいでした。

そもそも、前日の夜もAnsibleのs3_syncモジュールの挙動を確認しようとしたら、aws s3 lsService Unavailableでなんじゃこりゃ、Dockerでfakes3使っているからか?awsコマンドの問題か?プロキシ挟んでるのが問題か?などとPCをいじっていて何をトチ狂ったのかpython3を丸消ししたらgnome-sessionがまるっと消えてしまってログインしようとするとFailed to start sessionになってうへえってなるし(ctrl+alt+f1でCUIログインしてgnome-sessionとubuntu-sessionを入れ直した)、pip install awscliしようとしたらcould not find a version that satisfies the requirementってなるわで、何が問題かって-vオプションつけてpip installしたらHTTP Error 403: SSL is requiredって怒られて何がなんやねんってなってしょうがないからeasy_installでawscli入れたらすんなりインストール出来て、週末の夜にPythonなのか自分なのか変なのにドハマりしてうへえってなりながら朝5時くらいまでアズールレーンやりながら格闘していた。朝起きたら11時でそれもそれでげんなりしました。

発表についても、そもそも言いたいことが伝わっているのか、言いたいことがなんのかよく分からなくて、あんまり準備ができなくてすみません。

キャンセルする人が結構多かったこと

歌舞伎座.techの仕様(?)として、発表者はconnpassページの管理者になる、というものがありまして、管理者のばあい参加登録やキャンセルがメールで飛んでくるのですが、当日になるにしたがってキャンセル登録のメールがぽこぽこ来るようになりました。まあ勉強会っておよそ事前キャンセル多いから、しょうがないよね、と思いつつ、定員は80人だったけど実際来たのはたぶん15人から20人くらいじゃないかね?そもそも今日はJJUG CCCだったから人がそっちに流れちゃったのかもっていうのはあると思います。

OSSドキュメンテーション業のつらみ

私見ですが、ドキュメントは実際にプロダクトを使うときにこそ真価を発揮するものであって、ただ読んでいるだけでは、そのプロダクトの使い方についてはなんとなくベースでしか分からないです。分かるのは、使い方よりもアーキテクチャだとか、ドキュメントの読み方だとか、ソースコードの構成とか、使っているライブラリとか、そういうところです。

他の人はどういう考えでOSSのドキュメントをメンテしているかわからないですが、僕がOSSのドキュメントを直す理由はほぼ自己満足で、趣味です。typoがある、リンク切れしている、行末に空白がある、そんなのがなんとなく受け付けられないだけです。

「おっ、typoがあるぞ」ってなったらラッキーって感じで最近はドキュメントやソースコードを読んでいます。

C++のドキュメント整備の発表でもありましたが、ドキュメントのメンテはボランティア率が高く、ドキュメントのメンテは誰もやりたがらないので人が集まらないし、GitHubなどのホスティングサービスを利用しないでドキュメントを管理する場合サーバーは自前で用意しないといけないのでお金も必要になってくるので、突き詰めるとヒトとカネと時間の問題になります。

だから、typoだとか言語のゆらぎだとかリンク切れなどはある程度自動化して修正できたらいいなあっていうのは思います。C++のドキュメントをメンテしている方が、「メンテする人間が一人でもずっとやっていく」みたいなことを言っていて、いいこと言ってるなあと勝手に思いました。あと相変わらず江添さんは楽しそうに喋るので、見習いたいと思いました。どうやって見習ったらいいかわからないですけど。