良い記事を書くためのガイドラインとMarkdown記法のヒントを投稿画面に追加しました
こんにちは! uasi です。北海道旅行から帰ってきたら東京のほうが寒くて何か損した感じです。何も損してないはずなのに。
今回はQiitaの投稿画面の変更点についてお知らせします。
良い記事を書くためのガイドライン
投稿画面のエディタ上部に良い記事を書くためのガイドラインへのリンクを追加しました。
ガイドラインでは、Qiitaに投稿した記事が他の誰かの役に立つようにするために心がけるべき点を説明しています。初めてQiitaに投稿する方はもちろん、何度も記事を書いたことがある方も、一度目を通してみてください。
Markdown記法のヒント
投稿画面のプレビュー部分によく使うMarkdown記法の一覧を追加しました。一覧はプレビュー内容が空のときだけ表示されます。より詳しいヘルプを見るにはエディタ右上の?ボタンをクリックしてください。
以上です。マルセイバターサンドおいしい。
「情報のオープン化で開発―他部署をつなぐ橋ができた」株式会社Fablicさま Qiita Team利用事例
こんにちは、夏の暑さに負け気味の htomine です。
半袖で過ごせるのはいいけど外に出たくなくなりそうです!
さて、今回は最近リニューアルもされたフリマアプリ「Fril」を運営する株式会社Fablicの皆様にお話を聞いてきました。
チームの文化に合わせて、Qiita Teamの使い方が徐々に変わっていくところに注目です。
株式会社Fablicさまインタビュー
他部署との結びつきが弱い、情報共有のモチベーションが低い、アウトプットしても見てくれる人が少ない……など、社内でのコミュニケーションや情報伝達に問題意識を持つ企業は少なくないのでは。組織が大きくなればなるほど、その状況を変えるのは大変かもしれません。
現在70人のメンバーを抱え、フリマアプリ「Fril」(フリル)の企画・開発・運営を行うFablicでは、Qiita Teamを導入したことで、社内コミュニケーションを円滑にし、より強い組織を作るのに成功しています。彼らがどのように課題を解決してきたのか、お話を伺いました。
インタビューのポイント
Qiita Team導入によって、チームにどのような価値がもたらされたかを導き出す
Qiita Teamの実用的な使い方を見出して、理想的なチーム、コミュニケーションを生み出す
目次
- 会社概要
- 導入前の課題
- 日報を書く文化ができていなかった
- 利用者をどう増やすか
- 必要に応じてメンバーを追加していく
- 併用しているツール
- 開発との関わり、ITリテラシーによってツールを使い分ける
- どんな情報をどう共有するか
- Qiita Teamはフィードバックをもらい、改善を積み重ねていく場
- 自分の考えを共有する
- 情報をオープンにすれば、コミュニケーションは円滑になる
- レポートを投稿する
- サービスをより良くしていくための考え・情報をシェアする
- 導入〜浸透後の変化
- 開発チームと他チームとの間に架け橋ができた
- 文化を作る
- メンバーが必ず読んでくれるから投稿したくなる
会社概要
今回ご協力いただいた企業:株式会社Fablicさま
利用人数:31人(2015年7月15日現在)
ご利用開始年月日:2014年5月
導入前の課題は?
日報を書く文化ができていなかった
―Qiita Team導入前は、どのような課題を抱えていましたか?
竹渓さん:日報を書く文化がなかったことです。週次ミーティングで振り返りはしていて、議事録をGitHubのWikiにアップしていましたが、それだけでは日々誰が何をしているかが、あまりわからなかったんですよね。日報の所感などから伝わる人となりはもちろん、そのときどきで皆が考えていることをシェアできる場を作りたいな、というのが動機でした。
そんななか、長文を共有しやすいツールを探していたときに、Qiita Teamと出会って「これだ!」と。理由は2つあって、1つ目にマークダウン記法を使えること、2つ目にいいねでフィードバックできる機能があること。いいねのほうがコメントよりもライトなので、フィードバックする側もされる側もうれしいと思います。
導入したのは2014年5月です。開発チームが日報を投稿するためのツールとして、エンジニアを中心に約10人が使い始めました。現在は約70人のメンバーのうち、雇用形態を問わず開発に関わるメンバーを中心に31人がQiita Teamを使っています。
導入前を思い出しつつ語ってくださる竹渓さん(左)
利用者をどう増やすか
必要に応じてメンバーを追加していく
―初期の10人から今の31人まで、どんな段階を経て利用メンバーを増やしていったのですか?
竹渓さん:途中から日報だけではなく、振り返りの資料や仕様のたたき、キャンペーンの企画などもQiita Teamに書くようになったんです。その情報を開発チームしか見られない状況だと、開発に関連する他チームに不都合が生じまして。
金山さん:それもあって、私たち(コンテンツチーム、2人)は導入開始から3ヶ月後、比較的初期に追加されました。以前はEvernoteで日報を書いていたんですけどね。
竹渓さん:情報を見られなくて困る人が出てくる度に、必要に応じて追加していった形です。全メンバーに導入するのはコスト的に厳しいので、他のツールやサービスも併用しています。
コミュニティマネージャーの金山さん(左から3人目)
併用しているツール
開発との関わり、ITリテラシーによってツールを使い分ける
―たとえば、どのようなツールを何の用途で使っていますか?
竹渓さん:実は最近になって、日報はGoogle+(法人向け、社内限定公開)で管理するようになりました。日報くらいのボリュームの文章を書くのにちょうど良いですね。開発・ビジネス・カスタマーサポート別にコミュニティを作っています。
もともとGoogle Apps for Work(以下、Google Apps)は全メンバーが使っているんです。良くも悪くもQiita Teamはスモールなチームのためのツールだと思います。31人がそこへ日報を投稿すると、情報の流れがどうしても速くなってしまうんですね。
Google+を試してみたところ、いいねもできて、アプリも充実していて、スマホでも見やすくてと、使い勝手が良いことがわかりました。今はこの運用で上手くいっています。
金山さん:カスタマーサポートの女の子たちは、あまりITに強くないんですが、彼女たちも使いやすいと感じているみたいで、Google+での日報が定着しています。
どんな情報をどうやって共有しているか
Qiita Teamはフィードバックをもらい、改善を積み重ねていく場
―Qiita Teamの話に戻します。日報共有の場が変わった今、Qiita Teamにはどのような情報が投稿されていますか? 具体的な使い方も併せて教えてください。
竹渓さん:先日Frilがリニューアルし、男性も使えるようになりました。そのリニューアルに関する8割方の情報をQiita Team上でとりまとめていました。新たなサービスとしてのコンセプト定義やユーザーへのお知らせ文のたたきをアップして、関係各所からフィードバックをもらい、修正していく……といった使い方は良かったなと思います。
後半はプロジェクトを立てて、仕様や開発要件の全体像、ミーティングのメモなど、関連情報をできる限り紐付けていきました。Qiita Teamが長文を集約する唯一の場なので。
金山さん:他のツールはプロジェクトがかなり細かく分かれているので、どれを参照すると良いのかわかりづらい面があります。Qiita Teamだとタイトルをパッと見て判断しやすいというか、見つけやすいのがうれしいですね。開発メンバー以外でもとっつきやすいんです。
―その他、現在どんな投稿が行われていますか?
竹渓さん:最近では新着投稿が3〜5件/日あり、技術情報のまとめや月次の検索ワードTop50、施策の結果報告レポートなどが上がっています。わりと初期から投稿されていたのは、仕様のまとめやユーザーインタビューの結果報告レポートですね。
自分の考えを共有するために使う
情報をオープンにすれば、コミュニケーションは円滑になる
―使われ方に大きな変化が起きたのは、いつ何がきっかけでしたか?
竹渓さん:エンジニアの井坂さんが2月に入社してからですね。それまでは日報や要件定義など、硬質な情報ばかり投稿されていましたが、彼が社内で初めて自分の思いや気持ちを書いた人物なんです。
井坂さん:開発を始める前に自分の考えたことや思ったことを書いて共有するのが、前職の文化としてありました。それ自体がすごく良かったので、Fablicでも試してみたんです。もともと僕自身も、情報をオープンに共有すべきだという考えなので。
エンジニアの井坂さん(左端)
開発は一人でできることではありません。メンバーが何を考えているかがわからないと、なんとなく不信感が募ることもあるのではと思います。メンバーとのコミュニケーションを円滑にして、チームとしての開発力を上げて、より円滑に仕事ができるよう、常に考えをアウトプットできる空気を作りたかったんです。
金山さん:井坂さんが入社6日目に書いてくれたエントリー「なぜポエムを書くべきかというポエム」のおかげで、開発メンバーではなくても気軽に投稿して良いんだな、と感じられたのはありがたいです。
(エントリーを見ながら)いいねが10、コメントもたくさん付いていますね。カチッとした内容でないと投稿してはダメなんじゃないか、みたいな空気感を見事に打ち破ってくれましたよね。
竹渓さん:あのエントリーはかなりハラオチ感がありましたから。
井坂さん:結果的に「いろいろなことをオープンにしよう」といったFablicの文化と紐付いて、上手く機能するようになったと思っています。あれから「他サービスを使ってみた」「◯◯を体験してみた」みたいな、ふわっとした投稿も増えてきましたよね。
井坂さんの投稿した記事「『なぜポエムを書くべきか』というポエム」
基本的に、他人の考えていることはわからない。
何を考えているかわからない他人には不信感が募り、
不信感のある他人は無意識的に「敵」になる。― 記事中より引用
レポートを投稿する
サービスをより良くしていくための考え・情報をシェアする
―職種がバラバラな皆さんですが、それぞれどんな使い方をしていますか?
山口さん:私はAndroidのデザイナーなので仕様を書くことが多いです。自分の考えを書く頻度もけっこう高いですね。今までで一番ヒット(笑)したのは、2ヶ月ほど前に書いた「もっとユーザーと会う機会を増やしたほうがいいのでは?」みたいな投稿です。ユーザーイベントをしよう、と呼びかけたものです。
そもそも自分がどうしてAndroidを好きになったのか、過去を振り返ってみたんです。一番大きかったのは、Googleの中の人に会えて、すごく親切にしていただいた思い出でした。そのときに「私はもうずっとAndroidでいこう!」と決めたんです(笑)。
そういう体験は他のサービスでもあり得るんじゃないかな、と思ってエントリーを書きました。あのときに中の人と交流して、忘れられない素敵な思い出ができたから、そのサービスをさらに好きになり、長く使い続けたい……みたいな。
金山さん:以前は、競合他社さんや外部の方と情報交換をしたときのレポートや、各機能がどう使われているかといった報告を中心に投稿していました。実は私自身、Frilのヘビーユーザーでもあるので、最近はとくに自社と競合の違いをレポートするのに力を入れています。
ちょうど昨日投稿したエントリーがヒット作(笑)になりました。自社サービスをさらに使い倒そうという目的で、「ひとり出品強化月間」をやりますよと宣言したんです。いいねが16つきましたね。
みなさんの投稿を見せていただきながら話をお聞きしました。
導入〜浸透後の変化
開発チームと他チームとの間に架け橋ができた
―お話を伺っていると社内にQiita Teamがしっかり浸透した感があります。どんな変化を実感していますか?
金山さん:開発チームと他チームとの間の架け橋ができたと感じています。フィードバックをたくさんもらえるのがうれしいです。また、皆に情報を共有しようとする意識が、各自の中で強まってきているとも思いますね。
竹渓さん:2・3月に2回に分けて、社員全員で会社の文化について考える合宿を行ったんです。企業文化の明文化を目指しているんですが、その一つに「オープンに情報を共有する」というものがあります。Qiita Teamを使って発信する文化ができたこと、そういった企業文化が共感されたことで、自ら発信しようとする意識が強まったのかなと。
文化をつくる
メンバーが必ず読んでくれるから投稿したくなる
―最後に、Qiita Team導入後、社内に定着させるためにできることを教えてください。
竹渓さん:まずは日報からスタートして、それを見ていいねやコメントでフィードバックする文化をつくり、徐々に自分の考えや思いを発信できる環境を作っていくのが良いと思います。
井坂さん:そもそも僕が入社6日目にして、過去のエントリーとは違うカラーの内容を臆することなく書けたのは、メンバーが一つひとつの投稿を読む文化ができているのを感じたからです。自分の考えを伝えたら皆が見てくれる、というのは大きいです。
また、現場メンバーだけではなく、ファウンダー陣も投稿をじっくり読んでくれているんです。そういったことが伝わる環境だからこそ、Qiita Teamを使いたくなるんだなと思います。「皆で一緒に使おう」という雰囲気があると、自然な流れで文化として根付いていくのではないでしょうか。
―ありがとうございました。
・竹渓さん(取締役/デザイナー)
・井坂さん(エンジニア)
・金山さん(コミュニティマネージャー)
・山口さん(デザイナー)
(取材協力:池田園子)
Qiita Team 導入企業増加中!
数百のチームが、オープンな情報共有の場にQiita Teamを選んでいます。
あなたのチームにもそんな場所は用意されていますか?
30日間の無料トライアルでお試しください。
https://teams.qiita.com/
Qiita TeamのWebhookを少し改善しました
こんにちは、r7kamura です。暑い日が続きますが皆様イカがお過ごしですか。
Qiita Teamでは、メンバーが新しく追加されたときや、記事を作成したときなどに、予め登録しておいたURLに対してHTTPリクエストを送信するWebhookという機能を提供しています。このたび、Qiita TeamのWebhookの機能に少し改善を加えたのでお知らせします。
認証用トークン
本当にQiita Teamから送られたリクエストかどうかを確かめるための手段として、Webhookごとに固有のトークンが生成され、X-Qiita-Token
というリクエストヘッダにこの値が含まれるようになりました。Webhookのリクエストを受け取る側でトークンの内容が正しいものか検証することで、リクエストの偽装を防ぐことができます。トークンはWebhookの管理画面から確認できます (Webhookはチームの管理者しか設定できないのでご注意ください)。
ドキュメント
http://qiita.com/api/webhook/docsで公開しているWebhookのドキュメントを改善し、Webhookで送られるHTTPリクエストに関する説明や、イベントごとに送られるオブジェクトの型情報などを追記しました。
データ
記事の変更理由やコメントの作成日時など、これまで存在しなかった幾つかのプロパティを追加しました。詳しくはドキュメントをご覧ください。
おわり
Qiita TeamのWebhookの変更についてお知らせしました。Qiita TeamではSlackやHipChatとの連携機能なども提供していますが、Webhookを利用すればより自由度の高い処理も実現できます。 http://requestb.in/などを利用すれば簡単に試すことができるので、これまでWebhookを使ったことの無かった方もぜひ試してみてください。
学生歓迎!アシスタントデザイナーとイベント企画運営担当のアルバイトを募集します
最近暑くて出歩くのが大変ですね…konyです。
さて、弊社ではアルバイト募集を開始したのでお知らせします。
募集職種はタイトルにあるとおり、アシスタントデザイナーとイベント企画運営担当の2職種です。
すでに応募がきはじめているので、もし迷われている方がいたらとりあえずWantedlyから「話を聞きに行きたい」とご連絡ください 🙂
それぞれWantedlyに求人を掲載していますので、詳細は以下をご覧ください。
Kobito for Windows v1.5.0 リリース
こんにちは、@mizchi です。今朝からどうでもいい件でお騒がせしております。
まあそんなことはともかく、Kobito for Windows v1.5.0 について紹介させていただきたい!今回は要望が多かった機能を優先的に追加しているので、今まで興味がなかった人にも興味持ってもらえるように、という意気込みで機能追加しました。
新規のダウンロードはこちら: Kobito for Windows – ソフトウェア開発者のためのMarkdownによる情報記録・共有ソフト
ファイルの読み込み/書き出しに対応
要望が多かった機能です。
ファイルを指定して読み込みます。メニューの「記事 -> 開く」またはキーバインドのCtrl-Oから。
読み込み
書き出し
編集中の本文検索に対応
記事を編集中に本文を検索できるようになりました。Ctrl-Fで検索、Ctrl-Alt-Fで置換です。
その他の変更
- [機能追加] ファイル読み込み(Ctrl-O) に対応
- [機能追加] ファイル書き出しに対応
- [機能追加] preタグのプレビューに対応
- [機能追加] 編集中の検索に対応
- [機能追加] リスト要素での改行時により自然に補完が行われるように
- [機能追加] アプリ内から問い合わせ画面に飛べるように
- [機能追加] 記事の同期時刻を表示
- [変更] アップロード済みの記事でアップロードするかどうかを聞き直さないように
- [変更] ログイン画面のデザインを変更
- [バグ修正] 脚注のインデックスの番号の振られ方がおかしかったのを修正
- [バグ修正] テンプレートがQiita:Team と同じ順番で表示されるように
それじゃよろしくお願いします。
Qiita Teamで検索時に簡単に絞り込みができるようになりました
こんにちは、 yuku_t です。
Qiita Teamで検索結果に含まれるタグや投稿者の情報が表示されるようになりました。
目当ての情報が上位に出てこなかった場合、今までは自分で頑張ってクエリを考えて更新しなければなりませんでしたが、これにより簡単なクリック操作でより効果的に結果を絞り込むことができるようになります。
現在表示される絞り込み要素は「タグ」「ユーザー(投稿者)」「タイプ」の3種類です。例えば「タグ」の中の1つをクリックすると、そのタグだけが含まれるように検索結果が絞りこまれます。
また、各要素の右端にある数字は、そのボタンを使って何件まで絞り込まれるかを表しています。
どうぞご利用ください。
Kobito for Windows v1.4.0 リリース
こんにちは、 @mizchi です。最近はFF14の拡張版が出たのをきっかけに2年ぶりに復帰してマンドラゴラ鯖でレベリングに勤しんでいます。
というわけで!Kobito for Windows v1.4.0 リリースのお知らせです。既にお使いの方は次回の起動時にアップデータで自動的に更新されます。
新規のダウンロードはこちら: Kobito for Windows – ソフトウェア開発者のためのMarkdownによる情報記録・共有ソフト
v1.4.0 の主な追加機能
絵文字のプレビューに対応
プレビューでの絵文字の表示に対応しました。(絵文字の入力補完はv1.2.0から有効)
IME変換中に下線が出てなかった問題の修正
入力側で変換中に下線が出なくなってしまっていた問題を修正しました。
技術的な補足: CodeMirrorを使ったアプリケーションに共通に発生する問題です。forkでの対応しており、本家には採用されていません。また文節変換中の区切りには現在のところ未対応です。
パッチは以下で公開しています。 https://github.com/mizchi/CodeMirror/commit/4029493dd9d8362975f9b4562d26a4d463acc874
その他の変更
- [機能追加] 絵文字記法に対応(例:
:smile:
) - [機能追加] 設定画面に再ログインボタンを追加
- [変更] Ctrl+Hをバックスペースとして扱うように変更
- [バグ修正] 脚注記法のリンクが機能しないのを修正
- [バグ修正]
foo:bar
のようにコロンを含む文字列がエディタ上で誤って色付けされるのを修正 - [バグ修正] リスト要素の3段目がエディタ上で誤って色付けされるのを修正
- [バグ修正] 7文字以上の文字列がエディタ上で誤って色付けされることがあるのを修正
- [バグ修正] 「チーム>記事の取得」メニューが機能しないことがあるのを修正
- [バグ修正] ポップアップと通知が同時に表示されたとき画面がガタつくのを修正
- [バグ修正] 日本語入力時、変換中の文字列に下線が出ないのを修正
- [バグ修正] ログイン処理中にネットワークが切断されると起動できなくなることがあるのを修正
今回はmarkdown側に誤って色付けされてしまう問題に手を入れたりしました。
他、Kobito や Qiita にご意見ご要望がありましたら是非 support@qiita.com まで、または Qiita 右下の「ご意見」までお問い合わせください。
Qiita Teamで記事のコピーができるようになりました
こんにちは、 Qiita開発チームの yuku_t です。
Qiita Teamにおいて、すでに存在する記事から簡単に新しい下書きを作ることができるようになりました。
これまではmarkdownを表示してそれをコピー&ペーストするなどの処理が必要でしたが、数回のボタンクリックでできるようになります。
- 記事ページのトグルメニューを表示し、「コピーを作る」を選択します
- 記事の内容をコピーした新しい下書きが作られるので、それを編集し、投稿します。
どうぞご利用ください。
アイコン画像をアップロードできるようになりました
こんにちは、 Qiita開発チームの yuku_t です。
これまでQiitaとQiita Teamでは、ユーザアイコンとしてGravatar、Twitter、GitHubなどの外部サービスのものしか設定できませんでしたが、本日から手元の画像をアップロードできるようになりました。
- ユーザメニューから「アカウント設定」ページにアクセスし、”写真アップロード”をクリックし「プロフィール画像アップロード」ページを表示します。
- ファイルを選択をクリックし、画像ファイルを選択します。
- 「新しい画像をアップロードする」ボタンをクリックすると、プロフィール画像が選択した画像に置き換わります。
どうぞご利用ください。
画像の大きさについての注意点
長方形の画像がアップロードされた場合、自動的に真ん中の部分が正方形に切り取られます。現時点でアップロード時点で切り取り位置を指定することができないので、意図した通りの場所で切り取られない場合は、お手数ですが手元の環境で事前に正方形に整形したものをアップロードするようにお願いします。
Kobito for Windows v1.3.0 リリース
こんにちは、 @uasi です。最近は映画にハマっていて、先々週は新宿でマッド・マックスを観て先週は平和島で怒りのデス・ロードを観ました。今週末は立川で Mad Max: Fury Road を観ます。 I am awaited in Valhalla!
さて! Kobito for Windows v1.3.0 リリースのお知らせです。既にお使いの方は次回の起動時にアップデータで自動的に更新されます。
新規のダウンロードはこちら: Kobito for Windows – ソフトウェア開発者のためのMarkdownによる情報記録・共有ソフト
v1.3の主な追加機能
脚注のプレビューに対応しました。
チーム一覧にアイコンを表示するようにしました。
その他のバグ修正は変更履歴をご覧ください。
v1.2からの変更履歴
- [機能追加] 脚注のプレビューに対応
- [機能追加] チーム一覧の表示
- [変更] メニューから問い合わせ先を追加
- [変更] 編集画面で画面を閉じるときの確認ボタンのデフォルトのフォーカスを「終了」から「キャンセル」に
- [バグ修正] 編集画面で画面を閉じるときにShift+Tabで前の選択肢に移動できなかったのを修正
- [バグ修正] 正規表現として不完全なものを検索クエリを入力した時にエラーが起きていたのを修正
- [バグ修正] ポップアップが出現する時にガタつくことがあったのを修正
- [バグ修正] pやpreなど一部のHTMLタグを書くとエラーが起きていたのを修正
- [バグ修正] エラーポップアップで文字がはみ出していたのを修正
Kobito や Qiita にご意見ご要望がありましたら是非お寄せください! support@qiita.com または Qiita 右下の「ご意見」リンクで承っています。
投稿画面のUIを改善しました
こんにちは、@yujinakayamaです。
本日、QiitaとQiita Teamの投稿画面が新しくなりました!
以下、主な変更点をご紹介します
ウインドウにフィットする広い編集エリア
各テキストエリアがウインドウ全体まで広がるようになり、より快適で、記事の編集に集中できるレイアウトとなりました。
また、各テキストエリアは現在のウインドウサイズに対して常にフィットし、ウインドウがスクロールしなくなりました。そのため従来のUIで発生していた、「本文テキストエリアの端までスクロールした際にウインドウ全体までスクロールされてしまう」といった、不快だった挙動が解消されています。
スペース区切りでの複数タグ入力
タグの入力方法も変更しました。従来は一つのタグごとに一つの入力欄が存在しており、複数タグの入力方法が少し特殊な形になっていました。新しいUIではタグ入力欄は一つのみとなり、スペース区切りで複数のタグを入力できるようになりました。
タグのバージョンは、タグ:バージョン
という、コロンを使った記法で指定することが可能です。バージョンの指定は任意です。例えば、Ruby Rails:4.2.0
というような書式になります。
旧タグ入力欄
新タグ入力欄
おわりに
その他にも細かな改善を行っており、以前よりも快適に編集ができるようになっているかと思います。
より情報共有しやすくなったQiitaとQiita Teamを、ぜひご活用ください!
Kobito for Windows v1.2.0 リリース
kobito開発の @mizchi です。ここ最近はインクを飛ばすイカのことで頭がいっぱいだったのですが、やっとそれ以外のことが考えられるようになってきました。
さて、さきほどkobito for windowsをv1.2.0をリリースしました。既にお使いの方は次回の起動時にアップデータで自動的に更新されます。
新規のダウンロードはこちら: Kobito for Windows – ソフトウェア開発者のためのMarkdownによる情報記録・共有ソフト
v1.2の主な追加機能
拡大縮小ができます。キーバインドは Ctrl-+/- です。
Qiita:Team へアップロードした記事を共同編集化することが可能になりました。
v1.1からの変更履歴
- [機能追加] Qiita:Teamに共同編集記事を投稿できるように
- [機能追加] Qiita:Teamに投稿した記事を共同編集化できるように
- [機能追加] 文字サイズを拡大縮小できるように
- [機能追加] クリップボードから画像の貼り付けができるように
- [変更] 通知ポップアップの出現位置の修正
- [バグ修正] 検索クエリを入力したままチームを切り替えるとクエリが空のように見えていた問題を修正
- [バグ修正] HTML記法でpreタグを並べたときにエラーが出ていた問題を修正
- [バグ修正] メンションの直後にカーソルがあるときバックスペースが効かない問題を修正
- [バグ修正] タグの変換候補が1件に絞られたとき自動的に確定してしまう問題を修正
- [バグ修正] 画像アップロード完了後にスクロール位置が一番上に戻ってしまう問題を修正
kobitoは皆さんの声によって日々改善されていきます。よろしくおねがいします。
Qiita API v2のJSON Schemaを公開しました
こんにちは、r7kamura です。
最近は主にイカとして活動しており、カラフルな墨を掛け合う日々を送っています。
さて、QiitaおよびQiita Teamでは、Qiita API v2としてデータを操作するためのREST APIを公開しています。これまで開発者向けに APIドキュメント を提供していましたが、今回は主に機械向けのインターフェースとして、JSON Schemaで記述したREST APIのスキーマ定義 (以下スキーマ) を公開することになりました。具体的には、JSON Hyper-Schema draft v4 を利用して定義されています。
http://qiita.com/api/v2/schema
Qiita API v2のスキーマの説明
Qiita API v2のスキーマの構成について簡単に説明します。スキーマは http://qiita.com/api/v2/schema から取得できます。localeというURLクエリパラメータで日本語および英語を指定できるので、使いやすいほうをご利用ください。以下の例では、curlを利用してスキーマを取得しています。容量が少し大きく、改行などを含んでいないため、jq
や less
を利用すると少し読みやすくなるかもしれません。
$ curl http://qiita.com/api/v2/schema
$ curl http://qiita.com/api/v2/schema?locale=ja
$ curl http://qiita.com/api/v2/schema?locale=en
$ curl http://qiita.com/api/v2/schema?locale=en | jq .
$ curl http://qiita.com/api/v2/schema?locale=en | jq . | less
スキーマの中身は、以下のような構成になっています。最上位のpropertiesプロパティの中で、アクセストークンや認証済みユーザ、コメントなど、APIでどのようなリソースが提供されるかが示されており、また各リソースがどのようなプロパティを持つか、どのようなリンクを提供しているか、ということが定義されています。 http://qiita.com/api/v2/docs もこのスキーマを元に生成されているので、ドキュメントと照らし合わせながら読むと分かりやすいかと思います。
{
"description": "...",
"properties": {
"access_token": {
"description": "...",
"links": [...],
"properties:" {
"client_id": {...},
"scopes": {...},
"token": {...}
},
...
},
"authenticated_user": {...},
"comment": {...},
"expanded_template": {...},
...
},
"title": "..."
}
JSON Schemaの使われ方
スキーマには、どのようなリソースがAPIで提供されるか、それらがどのように表現されるか、それらを操作するためにどのようなエンドポイントが提供されているか、といった事柄が記述されています。
JSON Schemaのよく見る使われ方としては、任意のプログラミング言語用のクラスファイルをそこから生成したり、ドキュメントを自動生成したり、受け入れテストを用意したりといった例があります。Qiitaでも、APIドキュメントをスキーマから自動生成したり、Kobito for Mac用にObjective-Cのクラスファイルを生成したり、Kobito for Win用にAPIクライアントを生成したり、といった使い方をしています。例えば、以下のクライアントライブラリの一部の実装は、スキーマをもとに生成されています。
- https://github.com/increments/qiita-rb
- https://github.com/increments/qiita-js
また、Qiita API v2自身もJSON Schemaを元に実装やテストが用意されており、クライアントから送信されたデータの検閲に利用したり、定義されているインターフェースと異なるデータを返すような実装になっていないかどうかを確認したり、といった使い方をしています。実際には、以下のライブラリを組み合わせて実現しています。Rubyで書かれたリソース定義用のクラスがあり、そこからJSON Schemaを生成し、それをドキュメント生成やバリデーションの仕組みに利用しています。
- https://github.com/r7kamura/jdoc
- https://github.com/r7kamura/json_world
- https://github.com/r7kamura/rack-json_schema
なぜJSON Schemaを選んだか
まずスキーマを定義するに至った理由は、実装効率とコミュニケーションの問題です。
Web APIを提供するには、Webアプリ側で一貫性のあるWeb APIを実装して、テストを用意して、互換性のあるAPIドキュメントを用意して、それを利用するクライアントライブラリを用意して、クライアントアプリの開発用にダミーサーバを用意して、更にAPIに変更を加える際にはこれら全てが保たれるように慎重に処理を加えなければなりません。Incrementsのエンジニアは数人程度の規模ですから、あまり多くの労力は傾けられません。
また、多くの場合クライアントアプリケーションとWebアプリケーションの開発者は別々の人間が担当することになります。そのため、属人性を排し作業を円滑に行うために、1つの決められたプロトコルを元に作業を進められることが求められていました。そのようにWeb APIの仕様を決まった形式で記述する手段として、以下のような候補を考えました。
- JSON Schema
- RAML
- WADL
- Swagger
- Apiary
- 独自フォーマット
そこで、選定にあたって以下のような要件を考えました。
- スキーマからドキュメントを生成できること
- スキーマから他の言語のクライアントを生成できること
- スキーマからValidationルールを生成できること
- スキーマからテストを生成できること
- 知識を他で再利用・共有できること
- 自分でも全てのライブラリを実装できること
- 人間が読みやすいこと
- 機械が読みやすいこと
- すぐ捨てられること
これらの要件を満たす手段として、最終的にJSON Schemaに落ち着きました。
まとめ
Qiita API v2のスキーマを公開した旨をお知らせしました。JSON Schemaはほどほどに分かりやすく、ドキュメントや、テスト、バリデーション、コミュニケーションの道具として機能しています。公開しているスキーマは、JSON Schemaのサンプルとして利用したり、何か面白いものをつくってもらえると幸いです。公開した直後は、しばらくのあいだ些細な修正が加えられるかもしれませんが、ご理解いただければと思います。
Kobito for Windows v1.1 リリース
みなさん、イカがお過ごしでしょうか。開発の @mizchi です。諸事情で頭のなかがイカでいっぱいです。
というわけで開発は困難を極めました(?)が、なんとかv1.1をリリースしました。これが最初のマイナーリリースです。
最新版へのアップデート
既にお気づきの方もいらっしゃるかと思いますが、
現在ご利用中の皆様は 次回起動時に自動的にアップデート されます。
新しくダウンロードされる場合は公式サイトをご利用ください: Kobito for Windows – ソフトウェア開発者のためのMarkdownによる情報記録・共有ソフト
v1.1.0の変更点
- [機能追加] Inboxから他のグループへ記事を移動できるように
- [機能追加] コードブロックのシンタックスの入力で、ruby:code.rb のようなタイトルを入力できる
- [機能追加] アップデーターに正しい差分をダウンロードできたかのバイナリ検証を追加
- [バグ修正] チームが削除・サスペンドされた時にInboxへ移動するか削除するか選べるように
- [バグ修正] ハイライトでdiffモードを選択した時にエラーが出ていたのを修正
- [バグ修正] 起動失敗時にもアップデーターだけ起動できるように
- [バグ修正] エディタでのポップアップが矢印キーでも操作できるように
リリース後に頂いたご意見も参考にさせていただきながら、引き続き開発を進めていきます。今後ともよろしくお願いします。