新卒エンジニアから見たPLAID、そこで得られた経験と学び

<html><head></head><body><p>はじめまして、エンジニアの nito です。PLAID Advent Calendar 2018 の三日目の記事でもあります。</p>
<p>最近は KARTE の開発者向けのプラットフォーム開発を主戦場に、API の仕様策定や開発者向けの管理画面の実装、ドキュメンテーションなどを担当しています。</p>
<p>今回は <a href="https://support2.karte.io/update/2018/12/12347/" target="_blank" rel="noreferrer">12/3 にリリースした KARTE の開発者向けプラットフォーム「Developer Portal」</a> の開発をおこなううえで、大切にしていた <strong>Developer Experience (DX)</strong> という考え方をご紹介します。</p>
<h1 id="KARTE Developer Portal とは?">KARTE Developer Portal とは?</h1>
<p><a href="https://developers.karte.io" target="_blank" rel="noreferrer">KARTE Developer Portal</a> は KARTE が提供する開発者向けプラットフォームです。主に次の2つの機能で構成されています。</p>
<ul>
<li>ドキュメント: 具体的なユースケースに則した使いかの説明をするガイド・技術仕様を網羅するリファレンス</li>
<li>管理コンソール: KARTE の API や Webhook など開発者向けの機能にアクセスし管理する。</li>
</ul>
<p><img src="https://ik.imagekit.io/newt/61b151f921640c0018173598/5e45005b-8956-41e9-bad1-6f5a928e5788/Screen-Shot-2018-12-03-at-4.49.26.png" alt="Screen-Shot-2018-12-03-at-4.49.26"></p>
<h1 id="Developer Experience とは?">Developer Experience とは?</h1>
<p>DX は、2011年に UX Magazine で投稿された <a href="http://uxmag.com/articles/effective-developer-experience" target="_blank" rel="noreferrer">Effective Developer Experience</a> という記事で紹介されています。<br>
以下は一部引用したものになります。</p>
<blockquote>
<p>Platform product owners must be concerned with assisting developers in accomplishing this if end users are to have a good user experience overall. Attention to these details is called developer experience (DX), ...</p>
</blockquote>
<blockquote>
<p>(訳) エンドユーザーに、そのプラットフォーム上で、優れた体験をさせたいと考えているならば、プラットフォーム・オーナーは開発者がこれを達成するのを手助けしなければならない。そして、こうした開発者への細やかな配慮のことを Developer Experience (DX) と呼ぶ</p>
</blockquote>
<p>続けて、次のように言っています。</p>
<blockquote>
<p>and enabling app developers to be successful through better DX will create a more successful UX for the platform product.</p>
</blockquote>
<blockquote>
<p>(訳) より優れた DX を通して開発者を成功させることで、プラットフォームのユーザー体験をさらに成功させるだろう</p>
</blockquote>
<p>また、<a href="https://www.infoq.com/news/2015/10/api-developer-experience" target="_blank" rel="noreferrer">What is API Developer Experience and Why It Matters</a> では、API 設計に対して DX という考え方を拡げ、</p>
<blockquote>
<p>API developer experience is a relatively novel focus aimed to improve API design so it provides a seamless experience to developers when writing software. It can help increase programmers’ efficience and make it easier for developers to achieve goals on behalf of end users.</p>
</blockquote>
<blockquote>
<p>(訳) API Developer Experience は、API 設計を良くするための目標としては比較的新しく、開発者にシームレスな開発を可能とします。そして、プログラマーの効率をあげ、開発者がエンドユーザーの利益になるように目標達成するのを簡単にすることができます。</p>
</blockquote>
<p>と伝えています。</p>
<p>DX は、開発者が気持ちよく生産的に開発できるかどうかに注意を向け、開発者の体験を良くすることで、それが結果としてエンドユーザーの良い体験につながるという考え方です。</p>
<h1 id="KARTE Developer Portal で実際に注意したこと">KARTE Developer Portal で実際に注意したこと</h1>
<p>この考え方は、タイトルにもあるように、KARTE Developer Portal を開発する上で非常に大事にしています。<br>
ここからは、実際に DX を意識したところ、ここでは、とくにドキュメンテーションに関して気をつけたところを、いくつか紹介していきます。</p>
<h2 id="実際のユースケースに合わせたガイド">実際のユースケースに合わせたガイド</h2>
<p>KARTE Developer Portal のドキュメントでは、KARTE が提供している API やフロントエンドから利用できる JavaScript モジュールなどの仕様をリファレンスとして網羅しています。しかし、(開発者の方なら経験があるかと思いますが、) リファレンスだけで、すべてを理解するのはかなり厳しいと思われます。</p>
<p>そのため、リファレンスで記載されている各API や関数の使い方としてガイドを提供しています。ガイドは、どのような目的で、どのように使うのかを例 (サンプルコード) を交えて紹介しているので、開発者が迅速に開発に取り掛かることができます。</p>
<p>たとえば、以下は [ガイド] &gt; [基本的な使い方] の「チャットボット連携」に関するドキュメントのタイトルですが、目的から記事にたどり着けるようにタイトルをユースケースを表すようにしています。また記事ごとに目的をもったシナリオと捉えて、動詞をタイトルにしているのも工夫のひとつです。</p>
<pre><code class="language-plaintext hljs">チャットボットと繋げる
├── チャットボット連携のセットアップ
├── ユーザーにメッセージを送信する
├── ユーザーのメッセージを受け取る
├── ユーザーの担当者を変更する
└── ユーザーの担当者変更情報を受け取る

</code></pre>
<p><img src="https://ik.imagekit.io/newt/61b151f921640c0018173598/82c73a32-efa4-4018-81f1-13173007a1a7/Screen-Shot-2018-12-03-at-22.16.04.png" alt="Screen-Shot-2018-12-03-at-22.16.04"></p>
<h2 id="コンセプトを最小限で理解するためのチュートリアル">コンセプトを最小限で理解するためのチュートリアル</h2>
<p>また、そもそもプラットフォーム上で開発する場合、そのプラットフォームがどのようなプロダクトで、どのようなコンセプトを持ったプロダクトであるかを理解することも非常に重要になります。そこで、[クイックスタート] というチュートリアルを設けて、KARTE の最小限の基本的な機能をさらいながら、そのコンセプトを理解できるコンテンツも提供しています。</p>
<h1 id="おわりに">おわりに</h1>
<p>本記事では、Developer Experience という考え方を紹介しました。KARTE Developer Portal では、DX をもとに、紹介したドキュメントをはじめ、API 設計などにも適用しており、開発者、ひいては KARTE ユーザーに良い体験を提供することを目指しています。</p>
<p>CX（顧客体験）プラットフォーム「<a href="https://karte.io/" target="_blank" rel="noreferrer">KARTE</a>」を運営するプレイドでは、KARTEを使ってこんなアプリケーションが作りたい！ KARTE自体の開発に興味がある！というエンジニア（インターンも！）を募集しています。<br>
詳しくは<a href="https://plaid.co.jp/recruit/engineer.html" target="_blank" rel="noreferrer">弊社採用ページ</a>または<a href="https://www.wantedly.com/companies/plaid/projects" target="_blank" rel="noreferrer">Wantedly</a>をご覧ください。 もしくはお気軽に、下記の「話を聞きに行きたい」ボタンを押してください！</p>
<div class="wantedly-visit-button" data-visit-button-id="lyE
<p>_IgY4VF5ukBo_EUKZLg&quot; data-width=&quot;300&quot; data-height=&quot;60&quot;></div></p>
<script>
  (function(d, s, id) {
    var js, fjs = d.getElementsByTagName(s)[0];
    if (d.getElementById(id)) return;
      js = d.createElement(s); js.id = id;
      js.src = " https:="" platform.wantedly.com="" visit_buttons="" script.js";="" fjs.parentnode.insertbefore(js,="" fjs);="" }(document,="" "script",="" "wantedly-visit-buttons-wjs"));="" <="" script="">
</div></body></html>

開発者向けプラットフォームを開発するうえで大切にした「Developer Experience」という考え方; KARTE の開発者向けプラットフォーム「Developer Portal」の開発をおこなううえで、大切にしていた Developer Experience (DX) という考え方をご紹介します。
