株式会社クイックのWebサービス開発blog

HAPPYなサービスプランナー・エンジニア・デザイナーのブログです。

Laravel+Scribeで簡単にAPIドキュメントを作ってみる

こんにちは!ソフトウェアエンジニアのたろーです。

在宅勤務が増えて対面コミュニケーションが減った分、仕様書などのドキュメント類の重要さ改めて実感する機会が増えました。

そのような中で、
「とりあえずLaravelで作ったAPIの仕様書を簡単につくりたいなー」
「Swaggerは使ったことあるけど他にもっと簡単に使えるものないかな〜」
と思い調べていたところ、Scribeというツールにたどり着き軽い気持ちで使ってみたらとても簡単に導入できたので紹介しようと思います!

Scribeとは

  • Laravel対応のAPIドキュメントジェネレーター
  • PHPdocからAPI仕様書のwebページが作れる。
  • 仕様書上で実際にリクエスト投げてみるようなテストもできる。
  • PostmanやOpenAPI/Swaggerの設定ファイルの出力もできる。

などなど簡単にできる便利ツールです。
公式ドキュメント

サンプルAPI作成

とりあえずサンプル用に簡単なGETとPOSTのAPIを作ってみます。

$ php artisan make:controller Api/V1/HelloController

HelloController.php

<?php

namespace App\Http\Controllers\Api\V1;

use App\Http\Controllers\Controller;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

class HelloController extends Controller
{

    /**
     * (GET)名前を呼んで挨拶を返してくれるAPI
     *
     * @param Request $request
     * @return JsonResponse
     *
     */
    public function get(Request $request)
    {
        $name = $request->input('name','名無し');

        return response()->json([
            'message' => sprintf('Hello %sさん!!GETだよ!!', $name),
            'status'  => 200,
        ]);

    }

    /**
     * (POST)名前を呼んで挨拶を返してくれるAPI
     *
     * @param Request $request
     * @return JsonResponse
     *
     */
    public function post(Request $request)
    {
        $name = $request->input('name','名無し');

        return response()->json([
            'message' => sprintf('Hello %sさん!!POSTやで!!', $name),
            'status'  => 200,
        ]);

    }
}

routes/api.php

<?php

Route::get('/v1/hello', 'Api\V1\HelloController@get');
Route::post('/v1/hello', 'Api\V1\HelloController@post');

設定

Scribeインストール

composerでインストール

$ composer require --dev knuckleswtf/scribe
$ composer show -i

knuckleswtf/scribe   2.7.10    Generate API documentation for humans from your Laravel codebase

設定ファイル生成

$ php artisan vendor:publish --provider="Knuckles\Scribe\ScribeServiceProvider" --tag=scribe-config

基本的なインストール手順はこれだけです!

Scribe設定変更

設定ファイルがconfig/scribe.phpに吐き出されているので設定を変更します。

ルートのマッチパターン変更
今回はapiのみを対象にしたいのでroutes.match.prefixesをapiに変更します。

 /*
  * Match only routes whose paths match this pattern (use * as a wildcard to match any characters). Example: 'users/*'.
  */
 // 'prefixes' => ['*'],
 'prefixes' => ['api/*'],

環境に合わせて対象URLを変更
今回はビルトインサーバの8000ポートで動かします。

   /*
    * The base URL to be used in examples. If this is empty, Scribe will use the value of config('app.url').
    */
 // 'base_url' => null,
 'base_url' => 'http://localhost:8000',

設定をしなければconfig/app.phpのurlを自動で設定してくれます。環境のURLに合わせて変更してください。

PHPdoc修正

ドキュメント出力用にPHPdocを該当コントローラに記載していきます。

GETメソッド用
@queryParam はURLパラメータクエリを記載します。

パラメータ名 型 required|optional 説明

の順で記載です。

@response にはサンプルレスポンスを記載します。
レスポンスの直前にステータスコードを記載することでステータスコードごとにレスポンスを記載できます。
記載量が多くなってしまう場合は@responseFileというアノテーションで外部ファイルを読み込ませることもできるようです。

    /**
     * (GET)名前を呼んで挨拶を返してくれるAPI
     *
     * @param Request $request
     * @return JsonResponse
     *
     * @group hello
     * @queryParam name string  呼んで欲しい名前
     * @response 200{
     *   "message":"Hello 名無しさん!!GETだよ!!",
     *   "status" :200
     * }
     */
    public function get(Request $request)

POSTメソッド用
基本的にはGETと同じですが、今回はリクエストボディーを受け付けるので @queryParamでなく @bodyParam といアノテーションを記載します。

   /**
     * (POST)名前を呼んで挨拶を返してくれるAPI
     *
     * @param Request $request
     * @return JsonResponse
     *
     * @group hello
     * @bodyParam name string  呼んで欲しい名前
     * @response 200{
     *   "message":"Hello 名無しさん!!POSTやで!!",
     *   "status" :200
     * }
     */

他にもアノテーションが用意されており、ドキュント生成時のハンドリングが行えるので是非公式ドキュメントを読んでみてください。

動かしてみる

ドキュメント生成

ドキュメント生成
artisanコマンドが用意されており、実行することで生成、対象ディレクトリへ配布されます。

$ php artisan scribe:generate

ビルトインサーバ立ち上げ
今回はビルトインサーバで立ち上げます。実際にwebサーバやwebコンテナ上でアプリが立ち上がっている場合は不要です。

$ php artisan serve

APIドキュメント確認

http://localhost:8000/docs/index.htmlへブラウザでアクセスします。

f:id:aimstogeek:20210714113824p:plain

できました!! 今回作った2つのAPIが表示されています。
APIのパスやパラメータ、サンプルレスポンスがroute.phpやPHPdocの内容に沿って表示されているのがわかります。

「Try it out」ボタンをクリックすると、リクエストパラメータに入力ボックスが表示されるので、ここから実際にAPIリクエストをなげてレスポンスを確認することもできます。 f:id:aimstogeek:20210714114803p:plain

感想

良いと思った点

  • とにかく導入と記述がとても簡単!
  • APIの設計と一部コーディングを並列で行える。
  • 簡単なテストであれば作成されたドキュメント上で行える。

気になる点

  • 複雑なAPIやフィールドやパラメータが多いAPIだとPHPdocがとても長くなる。
  • 個人的な感想ですが、主にレスポンスフィールド周りのドキュメントUIが少し見づらい。
  • APIモックを同時に作成したり、ドキュメントはドキュメントとして構成管理していく場合にはSwaggerの方が良さそう。

最後に

軽い気持ちで試してみたScribeですが想像以上に簡単に導入できてしまいました!
もっとリッチなことをやりたい場合はSwagger等を利用することも考慮に入れた方が良さそうですが、ScribeからSwaggerの設定ファイルを吐き出せるので、「とりあえずScribeでやってみて考えようか」くらいの気持ちで導入してみるのも良いかもしれません!

在宅勤務が増えコミュニケーションの方法が変化する中で、設計書やドキュメントの存在は非常に重要になってくると思いますので、充実化・整備しつつ自動化できるところは自動化して開発パフォーマンスを上げていきましょう!


\\『真のユーザーファーストでマーケットを創造する』仲間を募集中です!! //

919.jp

【zsh】と【Powerlevel10k】であなた好みのターミナルへ

こんにちは!入社2年目になったソフトウェアエンジニアのじゃがいもです!

最近ターミナルの環境を一新して、非常に作業しやすくなったのでご紹介します

zshとは

zshはシェルの種類の一つです。

正式名称は「Z Shell」で、読み方は(ゼット・シェル、ズィー・シェル)です。

スタンダードなシェルはbashですが、zshは様々なシェルのいいところを総取りした最強のシェルなのです!

macOSはCatalinaからデフォルトシェルがzshに変更されました。

support.apple.com

Powerlevel10kとは

zshにはコマンドラインの見た目を変えてくれる『テーマ』がたくさん存在するのですが、その中でも『処理速度』と『柔軟性』に重点を置いて開発されている有名なテーマがPowerlevel10kです。

1つ前のPowerlevel9kは公式でサポート外になったので、今お使いの方はPowerlevel10kに乗り換えをおすすめします。

f:id:aimstogeek:20210710114351p:plain

導入

今回はmacを使用して説明します。

windowsの方はwindows terminalからwslを使用して導入している方が多いです。

環境

MacBook Pro (13-inch, 2016)
macOS Big Sur 11.3.1
iTerm2 v3.4.8

iterm2インストール

デフォルトでインストールされているターミナルアプリは拡張性に乏しいので、『iTerm2』というターミナルアプリをインストールします。
便利な機能は後ほど紹介します!

iTerm2は公式サイトからダウンロードしてください。

iterm2.com

インストール後、以下のように起動できることを確認してください f:id:aimstogeek:20210710141757p:plain

zshインストール

echoで現在使用しているシェルを確認し、zshになっている方はOKです。それ以外の方はzshをインストールし、シェルを切り替えてください(zshインストールは割愛させていただきます)。

> echo $SHELL
/bin/zsh

/etc/shellsを見ると使用可能なシェルが分かります

> cat /etc/shells
# List of acceptable shells for chpass(1).
# Ftpd will not allow users to connect who are not using
# one of these shells.

/bin/bash
/bin/csh
/bin/dash
/bin/ksh
/bin/sh
/bin/tcsh
/bin/zsh

zshに変更する

> chsh -s /bin/zsh
// 変更後ターミナル再起動

Preztoインストール

1からzshの設定をするのは大変なので、zshのconfiguration frameworkを導入します。フレームワークには頼らず、自分でカスタマイズしたいよ!という方は飛ばしていただいて構いません。
元々私はoh-my-zshを使用していましたが、より高速な画面描画が可能なPreztoに乗り換えました。

リポジトリをclone
> git clone --recursive https://github.com/sorin-ionescu/prezto.git "${ZDOTDIR:-$HOME}/.zprezto"

これからホームディレクトリに以下のファイルを作成するので既存でこれらのファイルを使用している方がいたら、バックアップを作成してください
.zlogin
.zlogout
.zpreztorc
.zprofile
.zshenv
.zshrc

設定ファイルを作成
> setopt EXTENDED_GLOB
for rcfile in "${ZDOTDIR:-$HOME}"/.zprezto/runcoms/^README.md(.N); do
  ln -s "$rcfile" "${ZDOTDIR:-$HOME}/.${rcfile:t}"
done

ターミナル再起動

以下のように見た目が変わったら導入完了。

f:id:aimstogeek:20210710135249p:plain

github.com

Powerlevel10kインストール

リポジトリをclone
> git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ~/powerlevel10k

zshrcに設定書き込み
> echo 'source ~/powerlevel10k/powerlevel10k.zsh-theme' >>~/.zshrc


ターミナル再起動

以下のような設定画面が表示されたら成功

f:id:aimstogeek:20210710135306p:plain

ここからはPowerlevel10kの設定です。

好みのターミナルに仕上げていきましょう!
(戻る時はr、Yesはy、Noはn、止める時はqを選択してください)

以下は私好みの設定です。参考にしてください。

1, Install Meslo Nerd Font
yes
通常のフォントでは文字化けを起こすためインストールしています。

私は設定終了後にCicaというフォントをインストールして使用しています
↓おすすめフォント github.com

2, ターミナルの再起動

3, Does this look like a diamond?
ダイアモンドに見えていたらYes

4, Does this look like a lock?
ロックのマークに見えていたらYes

5, Does this look like a Debian logo?
Debianのロゴが見えていたらYes

6, Do all these icons fit between the crosses?
収まっていているのでYes

7, Prompt Style
(2) Classicを選択したいので『2』

8, Character Set
Unicode

9, Prompt Color
(3) Dark

10, Show current time?
(2) 24-hour format

11, Prompt Separators
(1) Angled

12, Prompt Heads
(4) Round

13, Prompt Tails
(5) Round

14, Prompt Height
(2) Two lines

15, Prompt Connection
(3) Solid

16, Prompt Frame
(2) Left

17, Prompt Spacing
(2) Sparse

18, Icons
(2) Many icons

19, Prompt Flow
(2) Fluent

20, Enable Transient Prompt?
No

21, Instant Prompt Mode
(1) Verbose

22, Apply changes to ~/.zshrc?
Yes

ここまでで設定は終了です。

以下のような見た目になりました!

f:id:aimstogeek:20210710135324p:plain

github.com

デフォルトのエディタ設定

Preztoのデフォルトエディターの設定がnanoになっているのでvimに変更します。 ~/.zprofileの20行目あたりにあるEDITORとVISUALをnanoからvimに変更します。

> vim ~/.zprofile
export EDITOR='vim'
export VISUAL='vim'

// 反映
> source ~/.zprofile

iterm2設定

ここからはiterm2の設定に入ります。
透過率の設定、cpu使用率、メモリ使用率等が分かるStatus barの表示をしていきます。

1, 透過率の設定
iterm2 > Preferences > Profiles > Windows内のTransparencyをお好みで設定してください。合わせてBlurの設定もすると見やすくなります f:id:aimstogeek:20210710140917p:plain

2, Status barを表示
iterm2 > Preferences > Profiles > Session内のStatus bar enabledを選択 f:id:aimstogeek:20210710141325p:plain

Configure Status barを選択
欲しいコンポーネントを選択してください
※下部にあるAuto-Raibowを設定すると見た目が可愛くなります f:id:aimstogeek:20210710135416p:plain

3, Status barの位置を下部に設定
iterm2 > Preferences > Appearance > General内のStatus bar locationをBottomに設定 f:id:aimstogeek:20210710135534p:plain

4, Color設定
iterm2 > Preferences > Profiles > Colors内のColor Presetsを『pastel(Dark Background)』に設定 f:id:aimstogeek:20210710135616p:plain

iterm2 & zsh便利機能

・command + Dで画面分割
f:id:aimstogeek:20210710135640p:plain

・サジェスト時にtabや矢印で次の候補を選択することができる
f:id:aimstogeek:20210710135701p:plain

・入力されているコマンドから履歴を検索できる
f:id:aimstogeek:20210710135912p:plain

・cdコマンドの省略
f:id:aimstogeek:20210710135934p:plain

最後に

ここまで一緒に進めていただいた方は、カッコよくて使いやすいターミナルになったのではないでしょうか。

カスタマイズ箇所はまだまだたくさんあるので、あなた好みのターミナルへ仕上げてください。

ここまでお読みいただきありがとうございました。


\\ 『真のユーザーファーストでマーケットを創造する』仲間を募集中です!! //

919.jp

夏だ!リモートだ!LT大会だ!!

皆さんこんにちは!ねこです。
2021年7月2日に今年2度めの社内LT大会を開催しました!
在宅続きで人とのコミュニケーションに餓えた有志たちが勢いで企画し、勢いよく開催されます。

f:id:aimstogeek:20210705171208p:plain
やりましょう!

LT大会とは

IT界隈ではおなじみのあれです。
LTはLightning Talkの略で、5分程度の短いプレゼンのことです。 ライブコーディングや〇〇やってみたというタイトルで、作ったシステムをささっと動かして見せるようなエンジニアならではの発表が多く楽しいですよね。
どうしても時間をオーバーしてしまいがちなプレゼンで、制限時間ぴったりで起承転結させるようなプロプレゼンターの”技”を見れるのも醍醐味です。

クイックのLT大会

コロナ前は3〜4ヶ月ごとに定期的に開催されていましたが、密禁止!となってからは延期に延期を重ね、しばらくは無理だね…と開催を控えていました。
しかし在宅勤務も1年が経ち、フルリモートでmeetやzoomにみんなが慣れた頃、「そろそろLT大会をしたい!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!」という気持ちが爆発した私とyumeさんが高ぶった感情に任せて企画を進め、今年も無事開催されるようになったのでした。
勢いって大事ですね!

参加者はエンジニアだけに限らず、発表テーマもなんでもありのWeb事業企画開発室全体のイベントとして開催したところ、フルリモートで20名以上の発表者・50名以上の視聴者が集まり、部署全体のお祭りのようになりました。

スプシで発表者を募集すると初心者枠も22時台の発表枠も埋まったり f:id:aimstogeek:20210706080436p:plain 専用チャットのメッセージが一晩で999を超えたりします! f:id:aimstogeek:20210705173129p:plain

今回のLT大会

今回もzoomでフルリモート&金曜夜業務後の開催となり、大盛況となりました!

デザイナーのネモトマがzoomの背景を作ってくれたり

f:id:aimstogeek:20210705174724p:plain
きゃわわ!

ちーかまがスプラの生配信始めたり f:id:aimstogeek:20210705175425p:plain

プランナーのYさんが推しと歩む人生を語ったり f:id:aimstogeek:20210705190500p:plain

matsBさんが家庭で怒られてる話をしたり f:id:aimstogeek:20210705175057p:plain

とにかく多種多様で個性的な発表がたくさんされ、とってもとっても楽しかったです!
今回は「推し」の話が発表者の半分以上を占める中、私はスプシでアドオン使わずにガントチャートを作ったよっていう比較的真面目なネタのLTをしました。
前日深夜に「これそんなにおもしろくなくね?」ってなって1回まるっとスライドを作り直したのはいい思い出です。

f:id:aimstogeek:20210705174214p:plain
スプシの小ネタをいっぱい詰め込みました

まとめ

LT大会は当日もすっごい楽しいんですが、在宅勤務で同じ部署でも隣の席の人でさえなかなか会えなくなってしまった昨今、みんなの興味関心が知れて、ちょっとした話題ができるのがたいへんうれしいですね!
今日もついつい「あの人のアレめちゃくちゃおもしろかったよね〜w」「次やるとしたら何で発表する?」とお昼に盛り上がってしまいました。
ほんの数日前にやったばかりなのにもう既に次回がたのしみでしょうがありません。
発表ネタを探して毎日生きていこうと思います。

次回はおそらく10月頃に開催されるので、そのときのレポもお楽しみに!(きっとだれかがやってくれるはず!)
では〜〜〜!


\\ LTにも興味あり!な『真のユーザーファーストでマーケットを創造する』仲間を募集中です!! //

919.jp

コピーライティングとは本当に「ラブレターを書くこと」なのか?

こんにちは。 2課デザインチームでコピーライター兼デザイナーをやっております、ケイと申します。

いかにもラブレターが入っていそうな学校の下駄箱

先日、ついに完結を迎えたエヴァンゲリオン新劇場版シリーズ。 第2作目の『破』にこんなシーンがあるのですが、ご存じでしょうか?

転校してきて間もない式波・アスカ・ラングレーが学校の下駄箱を開けたとたん、大量のラブレターがなだれ落ちてくる。

平穏な日常を描いた何気ないシーンなのですが、ぼくは劇場で戦慄が走りました。 シンエヴァの予習がてらDVDで見返したときも、やっぱり背中が寒くなりました。

「大量のコピーがスパム扱いされている…」

古今東西、コピーはラブレターによく例えられてきました。

20世紀後半には、テレビ・新聞・ラジオ・交通広告を中心に活躍してきたコピーライターの大御所たちが「広告はラブレターである」と説き、 2000年代には、セールスコピーライターが「ラブレター理論」というテクニックとして、コピーライティングをラブレターに例えていました。

広告とは、商品と消費者をつなぐもの。 コトバの力で相手を振り向かせるわけですから、例え話としてはとてもわかりやすいですね。

ぼくも若かった頃は「お客さんにラブレターを書くつもりで良いコピーを考えるぞ」と肝に銘じていましたし、社内向けのコピーライティング講座みたいなものでも、「コピーってラブレターなんだよ」と伝えておりました。

でも。 心を込めて書かれたはずの珠玉のラブレターが、アスカの前ではスパムメールと化している!

なぜ、ラブレター=コピーは大量死してしまったのか? 「コピーはラブレター」というコトバを信じてきた人間としては、この問題の真相を考えずにはいられませんでした。

ラブレターの大量死

ラブレターは書き手本位になりやすい

アスカの元に大量のラブレターが押し寄せたのは、彼女が転校してきて間もないタイミングでのことでした。 それまで海外で過ごしてきた彼女のことを、あの学校に深く理解する人間がいたとは思えません。

そんな中、ラブレターは手紙なので、面と向かって話すより、素直に大胆に自分の気持ちを言葉にすることができます。 小綺麗な白い封筒に入れて、相手の下駄箱にしのばせておけば、相手の答えを目の前でドキドキ待つ必要もありません。

面と向かって言えないことを好きなだけ書ききって、あとは祈る思いで下駄箱にそっと入れるだけ。

好きな人がその手紙を読んでどんな表情をしたのか、下駄箱を開けて封筒を見た瞬間の気持ちはどうだったのか。 自分の書いたラブレターがアスカに読まれたのかどうか、最後まで見届けた者が果たして何人いたのでしょうか。

一方的に思いをつづり、祈るように下駄箱へ投函。 あとは自分からは何もせず、相手から返事が来るのをただ待つばかり。

…あれ、なんだかラブレターって、すごく書き手本位では…?

広告もラブレターも、書き手本意だから刺さらない。

個人的な所感ですが、広告制作は、ある意味、自分本位との戦いでもあります。 表現という行為自体とても主観的であるにも関わらず、 届けたい相手に寄り添い、徹底的に主観を排除してこそ、刺さる広告が作れます。

今や、「広告はラブレター」と言われ始めた昭和の時代とは比較にならないほど、 世の中にはモノや情報があふれています。 電車内で、中吊り広告とデジタルサイネージスマホが乗客の目を奪い合っているように、広告の種類と数は驚くほどに増え、コミュニケーションのあり方も多様化しました。

それは、裏返すと、ラブレターのなだれのように、 ひとつひとつの広告がユーザーに無視される可能性も増えている、ということ。

ユーザーのインサイトもレスポンスも正確な分析が可能な今、 コピーライターの「書き手本位」は広告の死を招きます。

こんな時代だからこそ、「コピーはラブレター」というコトバの先を強く意識する必要があるのではないでしょうか?

つまるところ、 絶対にフラれたくない相手に確実に届いて、 確実に刺さる、気持ちの伝え方とは何なのか。

「ラブレターを書く」のその先へ

とことん相手に目を向けて、相手の心を想像し、 相手がYesと言いたくなる内容を実現するために、 できることはないだろうかと思考する。

「下駄箱」よりももっと競合優位性が高く、 相手が周囲の目を気にしなくてすむシチュエーションがないだろうか。

封筒だって、もっと相手に相応しいデザインや配色があるかもしれない。 捨てられない、大事に扱いたくなる、つい中を開けたくなる… 工夫の余地はいくらでもあるのです。

もしかしたら、ラブレターではなく、直接相手に声をかけた方がいいかもしれない。 先にLINEを聞いて、メッセージの往復で関係性をあたためていくべきかもしれない。

ロマンチックじゃないかもしれないけれど、コピーで相手の心を動かしてYesを引き出す役割は、恋い焦がれた純朴な少年より、策をめぐらす策略家の方が向いています。

これからコピーライティングを学ぶ人たちには、 そんな「良い意味での計算高さ」を大切にしてほしいから、 ぼくは、社内の勉強会で「コピーはラブレターだ」ということをやめました。

そもそもクイックのWeb事業企画開発室は、自社の集客を手がけるインハウス部隊です。

広告の中身だけでなく、どんな媒体でどんなキャンペーンを展開するか、 広告と連動してどんなことを仕掛けていくか… 目的の達成のためにコミュニケーションシナリオ全体を設計できる裁量が、 我々コピーライターにはあるのですから。

919.jp

コンテクストと共通認識についての雑文

こんちは!最近Cvlteしか聴いていないhamanokamiです!

いきなりですが、今回は趣向を変えて、コンテクストをテーマに雑文を書いていこうと思います!

念の為コンテクストについて補足すると、

「コンテクスト」(Context)は文脈、脈絡、状況と訳され、コミュニケーションの基盤となる文化の共有度合いといった意味で使われます。また、「ハイコンテクスト文化」とはコンテクストの共有性が高く、一つひとつ言葉で説明しなくても察し合うことでわかる文化のことで、日本は世界でもハイコンテクストな国として知られています。その逆は「ローコンテクスト文化」で、明確な言葉での説明が求められる文化をいいます。(出典:https://jinjibu.jp/keyword/detl/893/

という意味です。

なぜこのテーマで書こうと思ったか

私が所属しているWeb事業企画開発室は、ここ1年で組織構造や評価制度の変更など組織変革の真っ最中なのですが、それと同時に徐々にローコンテクストな組織へと移行しているからです。

私達が掲げるミッション・ビジョンを達成するためには、多くの人と関わりながらチーム一丸となり仕事をする必要がありますが、 各自生きてきた環境・価値観などが異なるため、共通の認識を取れるように言語化や仕組みづくりすることで、達成の確度を上げることに繋がります。

ローコンテクストになっているから受け身で待っていればいいのかというとそうではなく、ハイコンテクストだと思うところは知りに行く、形式知にできるのであればしていくなどの動きを各自が取ることが求められています。

なぜなら個人と組織は別個のものではなく、個人は組織の構成要素であり、意識していなくても組織に影響を与えているからです。

共通認識を持つには

全員が共通認識を持つにはどうすればいいか? これはどの組織でもぶち当たったことのある課題だと思います。

関係者全員が共通の認識を持つって、めっちゃむずいです。

例えば、「犬」ということばを聞くと、 - 犬という概念そのもの - 「狆」という犬種 - 自分が飼っているタロー など、人それぞれ思い浮かべることは違う結果になります。

「普通名詞使っているから、当たり前だろ!」ってツッコミはあると思いますが、その前に文脈として、「小学1年生で習う漢字」というものがあれば、「漢字の犬」を全員が共通して思い浮かべると思います。(強引な例え話ですが、ツッコミはなしで...

クイックでは関係者間で共通認識を持てるように、共通言語をつくり実践している事例が最近のブログで投稿されているので、興味のある方はぜひ読んでみてください!

aimstogeek.hatenablog.com

aimstogeek.hatenablog.com

抽象的なことを理解するために、コンテクストを知る・結びつける

より具体的にすることで共通認識をもつことは可能ですが、ときには抽象的なことでも共通認識をもつことが必要になってきます。

抽象的な概念を理解するとき、コンテクストは非常に大事な要素の1つだと、私は思っています。

Web事業企画開発室では、仕事に臨む上でメンバーに持っていて欲しい大事な要素を、『OUR SPIRITS』として掲げています。

OUR SPIRITS

  • QUEST [探求]
  • CREATE [創造]
  • GRIT [情熱と粘り強さ]

この3つを見ただけでは、「うんうん、仕事で大事そうやな」で終わってしまいそうです。

では下記ミッション・ビジョンと紐付けて見るとどうでしょうか?

ミッション

  • 真のユーザーファーストでマーケットを創造する

ビジョン

  • 既存事業の成長を加速させ業界No.1にする
  • 事業の柱となる新規Webサービスを創る
  • クイック全社のIT活用を推進する

何のためにそれぞれのOUR SPIRITSが定義されていて、どのような行動を取ればよいか、初見の方でもある程度想像ができたのではないでしょうか?

仕事上では、上位概念と紐付けて考えれば、だいたいのことは理解できると思います。

それでも良く理解できない場合は、聞いてみる! それしかないです!

最後に

今回はかなり強引に論理を展開してきましたが、言うは易く行うは難しなんですよね。

共通言語つくるにしても、つくる過程で困難もありますし、つくった後にそれを定着させるという困難もあります。

ただ、こういった活動を地道にやっていくことでしか共通認識を持つことはできないので、その活動を粘り強くコツコツとされている方はすごいなと尊敬します!

まさにGRIT!

ということで、今回はここまで!

次回は強引な論理を使わないで説明できるようにがんばろ(☝ ՞ਊ ՞)☝


\\『真のユーザーファーストでマーケットを創造する』仲間を募集中です!! //

919.jp

簡単に書けるクラス図

こんにちは、みっきーです。

最近、初めてまともにクラス図を書き始めました。
仕組みや設計の理解が容易に行え、説明時にも活用できることに感動!
今回はこの感動を伝えたいので、感想とともにどのように書き進めたか書きたいと思います。

この記事の対象

クラス図を書いてみたい方
書こうと意気込んだけど書き進めることに挫折した方

※クラス図自体の細かい書き方は記載していません。

書き進めた手順

  1. テンプレートを作る
  2. クラスを書き出す

1. テンプレートをつくる

書き方をまるっと暗記することから始めるのはめんどくさいので、書き方を貼り付けました。 プログラム上でよく使われているもの、記載に必要なもののみ書き出しています。 クラス図の配置場所に迷うこともあったので、レイヤーが分かれるように背景も作りました。

f:id:aimstogeek:20210611105746p:plain
テンプレート

これで準備完了です!

2. クラスを書き出す

書き始める前にアラームを30分にセットします。 プログラムを読み始めると気になって寄り道しがちなので、そんな余裕は無くす作戦です!

ここからは一心不乱に読んでは書いてを繰り返します。 書き方がわからなくなっても検索せず、テンプレートをチラ見してコピーします。 ネットの海に乗り出さないようにする作戦です!

肝心の書き方ですが、最初は改修したい機能のリクエストを受け付ける(IN/OUTをしてそうな)クラスを見つけて書き出しました。

見つけたクラスが以下のような内容だったとして…

use App\Http\Controllers\XXXController;
use App\Http\Requests\UserSearchRequest;
use App\Services\UserSearchService;
use Symfony\Component\HttpFoundation\JsonResponse;

/**
 * Class UserSearchController
 * @package App\Http\Controllers
 */
class UserSearchController extends XXXController
{
    /**
     * @var UserSearchService
     */
    private $userSearchService;

    /**
     * UserController constructor.
     * @param UserSearchService $userSearchService
     */
    public function __construct(UserSearchService $userSearchService)
    {
        $this->userSearchService = $userSearchService;
    }

    /**
     * @param UserSearchRequest $request
     * @return JsonResponse
     */
    public function search(UserSearchRequest $request): JsonResponse
    {
        $validate = $request->validated();
        $options = [$validate->xxx];

        return $this->renderJson($this->quickSearchService->search($options));
    }
}

こんな感じにぺたり…

f:id:aimstogeek:20210611115337p:plain
呼び出されているクラスを書き出す

2番目にそのクラスが呼び出しているクラスを書きます。 全て書き出すのは大変なので、必要そうなものだけ書き出していきます。

f:id:aimstogeek:20210611120126p:plain
呼び出されているクラスを書き出す

3番目にクラスの関係を矢印でつなげていきます。

f:id:aimstogeek:20210611115422p:plain
矢印でつなげる

最後にメソッドやプロパティを書き込みます。このときも必要そうなもののみ書きます。 どこで何を使っているか分かれば良いので、型や引数などは省略したりしてます。

f:id:aimstogeek:20210611115447p:plain
メソッドを書き込む

以上がクラス図の一連の書き方です。あとは繰り返すだけです。
書き込みが足りなく感じるかもしれませんが、最低限書きだせば把握や整理は行えるのでこれで十分です。
簡単ですね!

ここから先は、作ったクラス図をベースに新しい機能を追加するもよし。
この図を見ながらリファクタ方針を決めるもよし。
複数人での開発時は、プログラムを読まずに仕組みの共有や実装範囲を決められるので便利ですね!

クラス図を書こうと思ったきっかけ

大きく3つあります。

1つは参画プロジェクトが変わったことです。
私にとって未知のプログラムの仕組みを1から理解する必要がありました。
複雑かつ規模が大きいため、読み進めても脳が疲労するだけで把握できませんでした。
とほほ…

2つめは開発効率を上げる必要があったことです。
鈍化する原因がクラス設計にありそうだと踏んだTLの号令で、いい感じに整理しながら進めることになりました。
未知のプログラムを!いい感じに!リファクタ…!
これは把握しなきゃ進められないですね٩( ᐛ )و

3つめは複数人での開発だったためです。
「ここをこうリファクタしたいんだよね」ってプログラムベースで伝えていくのはとっても大変。 どういう仕組みになっているのか双方理解した状態で行わなければなりません。 いちいちプログラムを追い直す必要があったりします。

この3つがきっかけなのですが、デグレ回避や事前にコンフリクトをキャッチできるので、無駄な作業やモチベーション低下を防ぐのにも役立ちました。
クラス図に手を伸ばすきっかけをくれたPJに感謝。

まとめ

クラス図を書くことによる恩恵はとても大きいです。
「書いたことない」が理由で書かないのはもったいないです。 1度書くと、2回目からは抵抗なく書き進められますよ!
ぜひ、試してみてください。

今までクラス図を書いてなかったのかとツッコミをもらいそうだな。笑
いつから書き始めてもよいのだ。


\\『真のユーザーファーストでマーケットを創造する』仲間を募集中です!! //

919.jp

リードエンジニアに必要な考え方について聞いてみたよ!

こんにちは!!フルーツパーラーです。

在宅勤務に慣れましたか?
以前は1日6,000-8,000歩くらい歩いていましたが、
在宅では1,000もいかない日があります。
これは体に重りがつくはずですね。

前回はリードエンジニア候補に対して、
どのような質問を行っているか書きました。
今回はリードエンジニアの考え方について書いてみたいと思います。

aimstogeek.hatenablog.com

新卒採用や中途採用でクイックに声をかけて頂ける方の中に、
エンジニアの力を伸ばしていきたいと話される方が多いです。

力をつけるにはどうすればいいか?
何をすれば身につくのか?という質問が多くありましたので、
エンジニアリングをリードする方々に聞いて回りました。

同じ疑問を持っている方にお読み頂けたら嬉しいです。
(今回は技術面でのお話は出ません)

質問は3つです。
どのような答えが出るか、予想して読み進めると面白いと思います。

3つの質問をリードエンジニアに聞いてみた

それでは答えを見ていきましょう!
どんな答えが出るか楽しみですね!!


Q1:どんな人と働きたいですか?

  • 話しやすい人
  • 感情が安定している人
  • 仕事を選ばない人

スキルよりも人、考え方が初めに出てきました。
初めにこの3つが出る事から、いかに重要かがわかります。

リードエンジニアはチームのエンジニアを束ねて
同じ方向に向かわせる役割があります。
目的や目標達成のためにチームワークが行えるかが重要です。
挙げた内容を逆にしたエンジニアがチームに入ると、
チームを牽引する際に時間がかかるのは想像がつきますね。

スキルについては、自身よりも高いと思える人が身近にいると、
自分自身も燃えて成長できると感じているようです。

  • この人を超えたいと思える人
  • 目標となる人(だけど3年後には超えるからね笑 という関係)

一方で今の自分よりもスキルが離れすぎていると、
同じレベル感で課題を考えられない事もあるため、
スキルが離れすぎない方が良いという声もありました。

  • 話せないくらいレベルの違う人は逆にきつい

どういうエンジニアが「良いエンジニア」なのか、
どの部分で”目標”となり”この人を超えたい”と思うのか聞いてみました。

Q2:どんな人が良いエンジニアだと思いますか?

  • 人と話せる人、他職種と話せる
  • 目的がしっかりしていて走れる
  • ゴールがエンジニアリングの先にある
  • 課題を正しく認識して、適切な提案ができる
  • ゴールが何かは組織で決まっているので、同じ方向を向いてたどり着ける
  • 目的を達成するために、自分だけができる事でなく、人をまきこみ、引き出しが多い
  • 売上がだせる
  • 知識や経験から選択肢が広い
  • システム全部(上流から下流まで)できる
  • システムができて、営業もできて、チームをまとめられる

まとめると

  • コミュニケーション / 他職種との協働
  • 目的思考 / 課題発見・解決力が高い / 自走力
  • 組織への貢献意欲 / チームマネジメント
  • システム開発の開発工程を幅広く経験

リードエンジニアの皆さんとお話していて、
普段から意識されているからか、
挙げて頂いたスキルが高いと客観的に思います。
背景や経験を事細かに言葉には出さないのですが、
過去に多くの経験をしてきたのだろうと感じました。

それでは、次を聞いてみようと思います。

Q3:どうすれば良いエンジニアになれますか?

みんなの嫌がる仕事を受ける

  • やるしかない。全部やりますといって宣言する。
    そして大変だけどやる
  • みんながやらない事をやると、そういう知見がたまり、
    どこかで活かせるスキルを作れる

仕事を選ばない

  • 選んでいたら、選んだ先のものしかできない
  • 他のものが任されなくなる
  • なぜやらないといけないかを一つ一つ説明するなら、
    ちょっとレベルは落ちても意欲的な方にお願いする方が早い
  • 特定の分野しかできないと、仕事を任せられない期間が発生する

自分以外の事を考える

  • 自分のキャリアのことばかり考えない
  • 組織だから、自分ではなく成果(ゴール)の事を考えるスタンスが必要

基本的な考え方としては利他的な考えを持ち、仕事を選ばず、
他者がやらない事を積極的に拾っていく事だと理解しました。

  • 仕事を選ばないから、幅広く任せられる
  • 任せられた事で出来る事が増える
  • 出来る事が増えると、さらに広い範囲で機会が生まれる

良いスパイラルが起きて高い角度で成長し、より成長機会に出会えるのだと思います。
これからリードエンジニアを目指すという方はぜひ参考にしていただきたいです。

ちなみによくある質問もしました。

業務時間以外で勉強しますか?

  • そもそも勉強と思っていないがやっている
  • やるかやらないかは本人次第だが、勉強をしている人の方が
    結果を生んでいる確率は高い
  • 勉強すればアウトプットに良い影響がでる

「やっている」という意見ばかりでした。
ただし、勉強とは思っていなくアウトプットのために、
自分で必要だと思うから行動している。という考えでした。

まとめ

  • 仕事を選ばず何でもやってみる
  • 自分ができる事だけでなく他者がやらない事を積極的に拾う
  • 自分以外の事を考える(利他的)

お気づきだと思いますが、
これはエンジニアだから必要という事はなく職種は関係ありません。
仕事をする上での基本となる考え方だと思います。

すぐに身につく考え方でもありません。
時間をかけていくつも経験をして、初めて到達出来る考え方です。
気づいた時からスタートで良いと思いますが、すでに実践している方もいますので、
5年10年と経験(実践期間)に差がでます。

とは言っても思い立ったが吉日。
エンジニアリングの力をつけたいと考えている方は是非実践して頂きたいです。

リードエンジニアから話を聞き、
私自身も仕事を選ばず何でもやっていくぜ!そしてやりきるぜ!という気持ちです!

最後までお読み頂きありがとうございました〜〜


\\『真のユーザーファーストでマーケットを創造する』仲間を募集中です!! //

919.jp