こんにちは、crowdworks.jpの開発エンジニアをしている得能です。
クラウドワークスへの入社以来バックエンド開発のみ行ってきましたが、今年に入りフロントエンド開発の機会をいただけることになり、Vue.jsを使い新規画面実装などを行いました。 その際に、今後新しくcrowdworks.jpのフロントエンド開発を行う方々がスムーズに開発業務に入れるようにフロントエンド開発チュートリアルを作成しました。今回はその取組みについてお話したいと思います。
背景
crowdworks.jpはバックエンドはRuby on Rails、フロントエンドはERB、Vue.jsで開発されており、少しずつVue.jsで開発した画面への置き換えを進めています。
Ruby on Rails × Vue.jsの実装といえば、Vue.jsで画面実装、Ruby on RailsはAPIサーバーにする、がよくある構成かと思いますが、crowdworks.jpでは過去の実装を残しつつVue.jsに移行を進めているなどの理由もあり弊社特有の実装方法を確立しています。そのため、crowdworks.jpのフロントエンド開発を初めて行う方はまずそのような実装ルールを知る必要がありました。
実装方法は現在の実装コードを眺めればある程度理解できます。また、フロントエンド開発に必要な知識は社内のQiita Teamにまとめていただいており、誰もが閲覧できる状況にはなっていました。 しかし、私がいざ開発を始めてみるとコードを読み込むだけでは
- コード上では必須ファイルの名称などが明記されておらず見逃してしまう
- 実は共通コンポーネント、関数が定義されているが、読んだ実装コードではたまたま定義されていなかった
ということがありました。
また、Qiita Teamの資料については実装したあとから「資料あったのか〜」と感じることがいくつかありました。その資料に到達するまでの検索ワード、問いが実装の過程では思いつかなかったためと分析しています。
私の情報探索力が足りないというのも理由ではあると思いますが、一方で、これだけ見ておけば全体像を理解できると感じられるガイドブックのようなものがあれば、誰でも迷わずcrowdworks.jpのフロントエンド開発に必要な知見をスムーズに習得することができるのでは？とも感じました。
どんな形式のガイドブックが良いだろう…と考えた結果、チュートリアルの形式が良いのではないかと思い作成してみました。
フロントエンド開発チュートリアルの要件
チュートリアルは以下の要件で作成することにしました。
crowdworks.jpの開発特有の内容に絞る
チュートリアルで扱う内容はcrowdworks.jpのフロントエンド開発でのみ必要な知見に絞りました。例えば、必要なファイル、実装方法、開発ルール等です。
Vue.jsのrefやcomputedの機能などのようにVue.jsの公式ドキュメントを読めばわかる内容については触れないこととしました。
参考までにチュートリアルの各章の名前を記載します(一部名前を置き換えています)。
上記の内容を通じて以下の画面を作成するチュートリアルとなりました。機能としてはログインユーザー名の表示、リンク、クリック判定だけのとても単純なページではありますが、実装方法を習得するために必要な知識は網羅できたと思います。
各章に参考資料のリンクを集めておく
例えば、弊社のデザインシステムを使ってVueコンポーネントを実装する章に、以下のようにimgの設定方法についてまとめた記事のリンクを貼るなどしました。
このようなまとめ方をすることで、該当の章を学ぶついでに周辺知識も習得することができると考えました。 また、外部資料が各章と紐づくことでどの実装作業に関連する内容のものなのかがわかりやすくなり検索性も向上すると考えました。(例: Vueコンポーネントを実装する際に気をつけることないかな… -> チュートリアルのVueコンポーネントの実装方法の章を読んでみる -> 画像の設定方法にルールがあったのか！)
外部資料と内容が重複する説明は極力記述しない
既に外部資料で記述されている説明はチュートリアル内では極力書かず、外部資料を説明を読むように誘導するようにしました。
例えば、実装ルールなどがREADMEで定義されている場合、チュートリアル本文にも明記してしまうと、ルールが変更になった場合にREADMEとチュートリアルの両方を修正しなければいけなくなり保守性が落ちるためこのようにしました。 ただし、それにより説明がわかりにくくなるのはよくないので、あくまでも可能な限り書かない、にとどめています。
作成した結果
チュートリアルを作成して社内に周知した結果、以下の結果を得ることができました。
知識習得・業務に役立ったとの声
ありがたいことに、チュートリアル作成段階で触っていただいたり、また、今年の新入社員のオンボーディングでも使っていただけました。 読者の技術習得のための努力や導入以前の環境の違いもありチュートリアル導入の効果の測定は難しいため、あくまでもヒアリング、いただいた感想からの内容になりますが、知識の習得に役立った、(既にフロントエンド開発に携わっている方から)なるほどと思う部分があった、などの良い反応を得られました。
また、実装業務中に実装方法を確認するためのチュートリアルを資料として参照する場面があるなど、知識習得のみならず業務においても役に立っているようでした。
自分のフロントエンド開発への解像度が上がった
チュートリアルをまとめる過程で知識があやふやになっていた箇所を調べたり、説明の誤りをいただき修正したりすることで、自分自身のcrowdworks.jpのフロントエンド開発への解像度がチュートリアル作成前よりも上がったと感じています。
学習したことのアウトプットとして記事を書くこと以上に細かく説明を書いたため、なぜそれをやるのか、問題点はなにがあるのか、他に参考になる知識はあるのか、など幅広く情報収集を行い、自分の中で整理することができました。
課題
チュートリアルは今回作成して自分が満足して終わり…ではなく、もし価値があるのであれば、可能な限り今後も使えるものとして運用して、できるだけ多くの人のフロントエンド開発入門のキッカケにしたい、とは思います。が、そのために特に保守面において課題があります。
修正の負担が重い
これはチュートリアルという方法を選択した時点でわかっていたことではありますが、開発環境の変化などによりチュートリアルを修正することとなった場合に修正のコストがものすごく重いです。
チュートリアル内の説明を少し変更するだけであればREADMEを書き換える感覚で修正が可能ですが、チュートリアルで利用している実装コードの変更、または、実装の一連の流れの説明の変更は大幅な修正作業が必要になるためコスト重めです。
自分以外の人が修正するのは難しい
チュートリアルはおおよそ24,000文字 + 実装コードで構成されているのですが、これを私以外の第三者が修正するのはものすごいハードルがあります。ちょっとした文言の修正では問題ないとは思いますが、一連の説明の文章を修正する場合、修正する文章の前後とちゃんと説明が違和感なくつながっているか、コード修正後も正しく動いているか、他の説明に影響のある修正になっていないか、など気にしなければいけない点が多くあります。「気付いた方は直してください」とお願いはしていますが、気付いた流れで直せるような文章量ではないでしょう。
チュートリアルを常に最新版にしておくことに温度感が高めだと考えられる方として、チュートリアルを体験した新入社員の方などがアタマに浮かびましたが、ヒアリングしたところ、習得したばかりというものあるのでいきなり直すのはハードルが高い、ということでした。それはそのとおり。
今後の展望
上記の課題はすぐに解決できるものではありませんし、ルールなどを強制して解決したいと思うものでもありません。自らの意思で、自然にチュートリアルの運用、保守活動に携わってくれるようになるにはどうしたらよいか？という観点で今後の展望を考えてみました。社内に浸透するよう地道にコツコツ取り組んでいくスタイルが良いと考えています。
修正を依頼するのではなく修正依頼を受け付ける形式にしてみる
自分以外の方に修正を依頼するのはハードルが高そうなので、修正依頼を受け付けて、その内容を見て自分が書く、という形式から初めてみても良いかな、と思いました。
チュートリアルを読んで修正に関する気付きがあった人は、簡単な質問でもいいので記事のコメント欄に書いてもらう形式です。結局自分が修正するというのは変わりませんが、修正する方向性がわかるだけでも文章作成の負担を幾分削減できます。
また、質問、依頼を通じてチュートリアルへの関心が高まり、ゆくゆくは自ら修正を試みてくれる方が現れるのでは？と思っています。
他の記事に引用して認知する機会を増やす
自分が他の方の記事を修正しなければ！と思うとしたらどんな状況か？と考えてみたところ、よく目にする、よくお世話になっている状況かな？と思いました。なので、チュートリアルの認知を高める、導線を増やすために今後作成する記事の説明に補助資料などとしてチュートリアルのリンク、引用などを貼るようにしたいな、と思っています。
あまりやりすぎるとよくないマーケティング臭がして逆に嫌われてしまうので、ちゃんとチュートリアルの説明が役に立つ場合にのみリンクを貼りたいと思います。あわよくば、他の誰かが記事を作成する際にチュートリアルの内容を引用してくれるようなことになれば最高です。
その取組みの結果、よくお世話になっているけど記事の内容が古いので直したいな…というマインドが出来上がれば…！と思っています。
終わりに
チュートリアルで一定の効果が出たぞ！今後も保守していくために頑張るぞ！という話でした。
今回チュートリアルという手段は良かったと思っていますが、一方で、チュートリアルという手段にはこだわっておらず、弊社のフロントエンド開発がよくなるのであれば他の良い方法も実践してみたいと思っているので、今後も日頃の実装業務に加えて環境改善に目を向けて仕事を頑張りたいです。
以上です、ありがとうございました。
最後に
crowdworks.jpのフロントエンド開発に興味のある方はぜひご連絡ください！ページの各機能のリニューアルが進んだり、デザインシステムの導入が活発になってきたりなど、かなりやりがいを感じることができる時期だと思っています。まずはカジュアル面談から、ぜひいっしょに働きましょう！
