【T3L】事例1:REST API

LINEで送る
Pocket
このエントリーをはてなブックマークに追加

あるIT関係の技術解説の文章を分解・分類・ラベリングした事例です。まず原文はこちら。

よく読まなくても大丈夫です。さらっと眺めたら次へどうぞ。

「REST API」とは、APIを呼び出すことでWebを通じてさまざまなサービスを利用できる仕組みのことです。

ここで出てくるREST(Representational State Transfer)とは、2000 年頃に Roy Fielding 氏が提唱した、分散アプリケーション構築においてコンポーネント間連携に適したサービスを構築する際の設計原則の集合のことです。
主に以下の4つ特徴があります。

(中略)

ポイントはRESTの設計原則がWeb技術と親和性が高いということです。

それに対し、REST APIはシンプルな設計で分散アプリケーションを実現できることや、すでに普及していたWebのHTTP通信でやりとりをできる手軽さ から人気となりました。
このとき、REST APIでのクライアント/サーバ間のデータの受け渡しには、軽量なデータ形式であるJSONが使用されることが一般的です。

(出典:http://www.knowledgewing.com/kw/blog/2017/02/201702230900.html?banner_id=ml_1977

 

これをこんなふうにラベリングしてみたんですが・・・

■ラベリング案?1

◆REST APIとはなにか?
【説明】APIを呼び出すことでWebを通じてさまざまなサービスを利用できる仕組み
【特徴】Web技術と親和性が高い
├【簡単】シンプルな設計で分散アプリケーションを実現できる
├【手軽】普及しているWebのHTTP通信でやりとりできる
└【速い】軽量なデータ形式であるJSONが使用できる

 

はい、なるほど、原文の一部を切り出して箇条書きにして、そこにラベル(見出し)をつけた、まずは真っ先にやっておきたい一番シンプルな方法ですね。
そうですね、ちょっと問題があるのは、「簡単」と「手軽」という2つのラベルです。これ、入れ替えたらどうなりますか?

入れ替えると・・・あれ? 入れ替えてもあんまり違和感ないなあ、、、

■ラベリング案?2(簡単・手軽 入れ替え版)

◆REST APIとはなにか?
【説明】APIを呼び出すことでWebを通じてさまざまなサービスを利用できる仕組み
【特徴】Web技術と親和性が高い
├【手軽】シンプルな設計で分散アプリケーションを実現できる
├【簡単】普及しているWebのHTTP通信でやりとりできる
└【速い】軽量なデータ形式であるJSONが使用できる

 

ですよね。「簡単」と「手軽」は意味が似てるから、入れ替えても通用してしまいます。こういう紛らわしい、似た意味のラベルを使ってしまうというのはよくある失敗の1つなんです。
(参考:ラベリングの基本 #2 入れ替え可能なラベルはダメ


あ、そうなんですか!


そうなんです。そこで、入れ替えられるラベルをうっかりつけてしまわないようにするためには、どうすればいいと思いますか? これは必ずやる失敗なので、「失敗しないように気をつける」というのは無理です。やっちゃった後で気がつく方法があればいいんです。


やっちゃった後で気がつくには・・・・実際入れ替えてみて、それで通じちゃうようならダメってことですよね


ええ、それで十分だと思います。それを習慣にしていれば、やってしまっても気がつきますし、気がついて直すのを何度か繰り返しているとだんだん最初から紛らわしくないラベルをつけられるようになりますよ。


なるほど! それならやれそうです!


あとはじゃあこのケースでどんなラベルをつけたらよいか、ですが、この話の場合は分類の組み換えからしたほうがいいですね。たとえばこんな感じでどうでしょうか。

 

■ラベリング案?3?(「用途」分離版)

◆REST APIとはなにか?
【説明】APIを呼び出すことでWebを通じてさまざまなサービスを利用できる仕組み
用途】分散アプリケーションの実装技術の1つ
【特徴】Web技術と親和性が高い
├【簡単】シンプルな設計が可能。普及しているWebのHTTP通信
|     でやりとりできる
└【速い】軽量なデータ形式であるJSONが使用できる

ああ、簡単と手軽を1つにまとめて、そこから用途を分けて別にしたんですね。確かにこのほうがいいですね。技術解説だし、用途の項目があったほうがいいです。


はい、今、「技術解説だし、用途の項目があったほうがいい」と言いましたよね? 実際その通りです。ラベルをつけると、そんなふうに、「この場面ではこの項目が必要だなあ」 ということに気がつくので、その後応用できるようになるんですよ。


そういえばそうですね!


はい、似たラベルを使ってしまうのは非常に良くある失敗ですけど、良くあるということを知ってさえいれば見つけやすいもので、しかもそれによって「考え直すきっかけ」が得られるので、今みたいに役に立つノウハウに気がつくことも多いです。ぜひ「ラベルをつけたら入れ替えてみる」のを習慣にしてください!


そうですね、了解です!

 

■まとめ

「長い文章をわかりやすく整理するための、よく使う3つの方法」として下記のようなものがあります。

この事例では主に「ラベリング」を使っています。

長い文章を分解・分類して短いラベル(見出し)をつけるのは、複雑な情報をわかりやすくするための基本中の基本です。しかしそれを一人でやろうと頑張っていてもなかなか難しいもの。それでも出来るようになりたい方は、ぜひ「Together! 3行ラベリング」を試してみてください!

Together! 3行ラベリング・メール添削トレーニングのお知らせ

コメント

タイトルとURLをコピーしました