• 3
    Like
  • 0
    Comment

初めに

Rails Girls Japan Advent Calendar 2016 の16日目を埋めさせていただきます。
(結果的に)前の記事は 15日目:ozamasa さんの Rails Girls と関わるいくつかの方法 でした。
この記事はそれを受ける形で、Rails Girls と関わるもう1つの方法の提案をします。
それは、ドキュメントの整備 です。

事例:インストールガイドの修正

まず、私が今年コーチとして参加した Rails GirsNagoya 3rd で実際に起きた、問題とその解決方法、それを Rails Girls ガイドドキュメントとして反映した事例を紹介します。

経緯

一日目夜の「インストールデイ」で、Windows に Rails 環境を構築するときに、問題が発生しました。
それは「gem update rails するときに Gem::RemoteFetcher::FetchError というエラーで落ちる」、というもの。

その解決策は、(その時点の)Rails Girls ガイド の インストールガイド にも載っていたのですが、情報が古く適用することができないものでした。
実は私も事前に「たぶんトラブるだろうなー」と問題視しており、その解決策(代替案)も用意していました1。それを試してみたら、見事、無事解決!23

「これ、インストールガイド修正した方が良いよね」

という話になり、帰宅してからその日のうちにドキュメント修正(依頼)・翌朝に修正反映された、というわけです。

手順・方法

具体的にドキュメントを修正した方法(概要)を簡単に紹介します。
要:GitHub アカウント、Ruby、bundler gem。

  • Github に上がっている ドキュメントのリポジトリ を fork する。
  • clone して、bundle installbundle exec jekyll serve --watch を実行する。
  • ブラウザで、編集対象のページを表示。
    • 今回の場合、http://localhost:4000/install#gemremotefetcher-

rails_install_guide_before_edit.png

  • 対象のページを編集(普通にテキストエディタで4
  • 編集結果確認(普通にブラウザをリロード)

rails_install_guide_after_edit.png

ドキュメントの整備

今回の事例は、実際にその場で発生した問題を起点に、その解決方法をドキュメントに反映(修正)した、というものでした。
そもそもそのような事態が発生した原因の一つが、「ドキュメントの内容が古かった」ということ。
Rails もその周りの環境も、日々更新されどんどん新しくなっていきます。それに「ドキュメントが追いつかない」というのは、常について回る問題ですよね。

ドキュメントを整備する。それって、立派な Contribution だと思うのです。

「スタッフに興味もあるけれど時間が…」「コーチできるほどのスキルが…」と躊躇しているあなた。
ドキュメントなら、技術的な面だけでなく、より良い手順の提案とか、「こんな Gem を使うとこんなことできるよ」という紹介とか、あなたにも貢献できることがあるかも。
少しの知識と最低限の日本語力があれば実行に移すのも気軽にできると思いますし56

終わりに

この場を借りて、オーガナイザー を務められた @ta8co_qiita さん初め、Rails Girls Nagoya 3rd に関わった皆さま、遅ればせながら、お疲れさまでした!

次の Rails Girls Nagoya 4th 開催時にもきっとコーチとして参加したいと思います。
あと、見てるかな、参加者で「金沢でもやりたい」と仰っていた方。開催の運びとなった暁にはきっとお手伝いに行きます!


  1. こちらの記事を参考にしました。→ Windows環境でgemがSSLエラー 2016 by @betrue12  

  2. 実はさらにもう1点、類似の問題も発生したのですが、原因も解決方法もほぼ同じ。こちらは想定外だったのですがその場で無事に解決!(bundler gem をアップデートしただけ) 

  3. Qiita なので技術情報も書こうかと思ったのですが、他の方の記事を参照しただけ1だし本題から逸れてしまうので省略します。詳細は 私が送ったプルリク 参照。 

  4. ドキュメントは Markdown 形式で書かれています。ので 編集には Markdown の基礎知識も必要ですね。  

  5. 編集方法の詳細は、GitHub リポジトリの README.md や、Rails Girls Guide の 自分流の手引きを送る手順 を参照してください。この記事では既存ページの編集だけですが、新しいページの追加方法も記載されています。 

  6. なお修正は GitHub の pull-request という形で依頼することになり、その時点できちんとレビューは入るので、色々安心です。 

This post is the No.16 article of Rails Girls Japan Advent Calendar 2016