AsciiDoc使ってみた

こんにちわ。コロナウイルスの影響で電車がガラガラの日々が続いていましたが、GW明けから徐々に出勤している人が増えているみたいですね。
電車混まないでえええ!!ということで、テックブログ今週の担当はuraです。

ドキュメント作るのつらい

皆さんは仕様書やマニュアルなどのドキュメントを作りますか?
私は現在受注プロジェクトのPMをしており、頻繁にドキュメントを作る機会があります。
一般的に、ドキュメントはWordやExcel等で作成するかと思います。WordやExcelは見やすいですよね。好きですか?私は嫌いです。

  • Gitで履歴管理しても簡単に文章を検索できない。差分も見えない。
  • チームで同じファイルを同時に編集しづらい。(GoogleDocsを使えばなんとかなるけど)
  • 書式を整えるのが面倒。気づいたら一部だけフォントが異なるとかよくある。
  • 顧客用のドキュメントであれば、修正の度にファイルを送信する必要がある。
ではどうするか?Markdownで作成してGitで管理しよう。
いちいちファイルを送るのは面倒なので、GitにプッシュしたらHTMLに変換してWebページに公開しよう。

いや、でもMarkdownだとテーブルのセル結合すらできないから、ちょっと複雑なドキュメントになると表現力が足りない・・・。

そんなことを考えているときに見つけたのが、今回のテーマのAsciiDocです。

AsciiDocとは?

Asciidocは軽量マークアップ言語の一つです。Markdownの仲間ですね。
以下のような採用事例があります。

Markdownと比較すると以下のような点が優れています。

  • テーブルのセル結合ができる
  • 相互参照が使える
  • 外部ファイルを読み込める(ソースコードをそのまま読み込んで表示したり、分けて作成したドキュメントをマージしたり・・・)
  • PlantUMLを直接書ける

使ってみる

それではさっそく使ってみます。

セクション

「=」の数で表現します。
== セクション1
=== セクション1.1
==== セクション1.1.1
== セクション2
== セクション3

リスト

「*」の数で表現します。
* リスト1
* リスト2
** インデント
*** さらにインデント

テーブル

[cols="1a,1a,1a",options="autowidth"]
|===
|1A|1B|1C
2+|「数値+」で横結合|2C
.2+|「.数値+」で縦結合|3B|3C
|4B
|* 4C
* リストを
* 入れることも可能
|===

画像

image::https://techblog.imagemagic.jp/wp-content/uploads/2018/11/%E6%8E%A1%E7%94%A8%E3%83%90%E3%83%8A%E3%83%BC.png[alt=代替テキスト, width="200" align="center"]

アンカー

アンカーは二重の「[」で表現します。
[[hogehoge]]

リンク

link:https://imagemagic.jp/recruit/[イメージ・マジックではエンジニアを募集中です。]

<<hogehoge, アンカーへのリンクは二重の「<」で表現します。>>

外部ファイルの読み込み

include::hogehoge.adoc[]

まとめ

AsciiDocの特徴や簡単な使い方について紹介しました。
現在マニュアル作成で使っていますが、やはりWordよりはラクをさせてもらっています。

インストール方法や詳しいリファレンスについては公式サイトをご覧ください。

使いやすいUIとは?

8月に入って暑い日が続いています。脱水には気を付けなければ・・・と思いつつコーヒーばかり飲んでいます。テックブログ、今週の担当は浦です。
最近は開発の上流工程を担当していたので、テックブログのテックってなんだっけ・・・と若干悩みつつ、今回は「使いやすいUI」とはなんぞや?というテーマで軽くまとめてみます。

ユーザーにとっての使いやすさ

使いやすいかどうか、直感的かどうかは、ユーザーによってそれぞれ異なります。
えーーーって思った方、すみません。ですが、業務アプリの設計過程で様々なお客さんとお話してきた経験上、今まで使っていたものに近いもの、見慣れたものを「使いやすい」とする人が大半でした。
どのようなUIに慣れているかは人によって異なるので、何を直感的と感じるかも人によって異なるわけです。
したがって、ここではユーザーの「慣れ」の要素は考慮せず、どのようなルールを持たせたUIがいいのか人間工学をもとに挙げてみます。
 

人間に合わせたUI設計のルール

1. 関連の高い要素は近づけて配置する

人間は、位置的に近くに配置されたものを関連のある情報として認識します。
例えば、画像とキャプションがその他の要素間より近くに配置されていれば、一目でどのキャプションがどの画像を説明しているのか判断できます。
逆に関連の低い要素間は、意識して余白を大きく取ることで区別しやすくなります。

2. 同じ要素・レイアウトを意識的に繰り返す

人間は、過去の体験から予測して行動します。
慣れたものは使いやすいと前述しましたが、それは1つのアプリ内でも同様のことがいえます。
ボタン配置等のレイアウトをどの画面でも統一すれば、何がどこにあるのかすぐわかるため、ユーザーは直感的に操作できます。

3. 重要な要素を左上から右下への対角線上に配置する

人間の視線は左上から右下へと移動します。「グーテンベルク・ダイアグラム」とも呼ばれますね。
例えば画面下部にボタンを配置している場合、重要な機能のボタンは右に置いた方が意識されやすいです。

4. 重要な要素は大きくする

何を当たり前のことを!と思われるかもしれませんが、人間の視線は大きいものから小さいものへ移動します。
情報の重要度によって表示する大きさを分けることは、シンプルですが効果が大きいと思います。

5. 関連の高い要素を同じ配色にする

人間の視線は同じ色のものへ移動します。
グルーピングできる要素同士や、重要度が同じ要素同士を同じ配色にすることで、関連要素を辿りやすくなります。

まとめ

人間工学的にどのようなUIが使いやすいか挙げてみました。
ちなみに、1.2. はデザインの4大原則の1つでもあります。
興味のある方は調べてみていただければと思います。

分かりやすいエンドポイントの設計

こんにちわ!やっとこさ入社1ヶ月半の浦です。
毎年この時期は花粉にやられています。ただただつらいです。鼻の粘膜を焼いてアレルギー反応が起こりづらくする治療もあるようですが、ちょっと怖いのでチャレンジできずにいます。花粉面倒なので、どなたかGWまでタイムリープする方法を知りませんか?

今回のテーマ

さて、現在私は【ODPS】 という、工場受注~生産管理までを一括で担うクラウド管理 システムの開発に携わっています。詳しくは以下のリンクをご覧いただければと思います。
https://imagemagic.jp/service/odps/

クラウド管理システムなので、当然ながらWebサービスです。
TwitterでもYouTubeでも何でもかまわないのですが、Webサービスのエンドポイントの設計って気になりませんか?個人的にはけっこう見ちゃうんですよね。
APIを使う際、URIの設計が悪いと使い方を理解しづらかったり、間違って使ってしまったり・・・。ということで今回は、分かりやすいエンドポイントの設計について考えてみたいと思います。

余計な情報がない

例えば、以下のURIを見てどう思われるでしょうか。
  • http://example.com/service/users/get
個人的な突っ込みどころは二つです。

1.「service」が抽象的

大抵「サービス」という単語が出てくると、より具体的な機能を当てはめた単語に置き換える必要があるか、その単語自体不要なことが多いかと思っています。

2. 「get」は不要

HTTPのメソッドで使い分ければいいですね。URIの指すリソースと、そのリソースに対する操作は分離できた方が見やすいです。

単語を省略しない

  • http://exapmle.com/sv/u
このURIを見て、どんなリソース・機能にアクセスするのか分かるでしょうか。「sv」は「service」かもしれませんし、「supervisor」かもしれません。「u」も省略し過ぎて「user」なのか判然としませんよね。
人間が見てどのような機能なのか理解できないURIは、タイプミスに繋がります。APIを公開してクライアントにアクセスしてもらうことになった場合、上に挙げたような理解しづらいURIは、クライアントの開発効率の低下に繋がると考えます。

大文字小文字が混在していない

大文字小文字が混在しているとは、例えば以下のようなケースです。
  • http://example.com/Users/0123
URIのすべてが小文字に統一されていれば、この単語は大文字だったっけ?と迷うことがなくなります。また、ホスト名の部分はすべて小文字での表記が一般的ですので、それに合わせてすべて小文字にするのが良しとされているようです。

集合は複数形

  • http://example.com/user/0123
一見上記URIは、意味も分かりますし適切に思えます。しかし、上記URIの示すところは、「ユーザー」という集合の中の、「0123」というリソースです。データベースのテーブル名は一般的に複数形が適切といわれているのと同様で、集合を表すものは複数形にするのが一般的です。

まとめ

簡単ではありますが、今回は分かりやすいエンドポイントの設計について考えてみました。
エンドポイントの設計にご興味のある方は、ProgrammableWebという様々なAPIをまとめたサイトがお薦めです。各サービスがどのようなエンドポイントになっているか眺めるだけでも勉強になります。
URIの設計に限らずコーディングもそうですが、分かりやすさという観点は忘れずに今後の開発に取り組んでいきたいものです。