その1を公開してからだいぶ時間が経ってしまいましたが、その2を公開します。今回はドキュメンテーション編です。

レビュー対象ははてなダイアリーAtomPubの仕様書です。普段私が業務で仕様書をレビューするときに気をつけている観点をご紹介しながら、いくつか指摘をしてみます。

なお、レビューの指摘はどうしても細かくなってしまうので、粗探し的と感じられてしまうかもしれませんが、技術的な完成度を上げるためには必要な作業なのでご容赦ください。

基本的な文章チェック

まず、仕様書に記述されている文章の「てにをは」や文法レベルでのチェックをします。表記ゆれなども含まれます。

今回の仕様書は、たとえば以下のような記述がありました。

• 「ヘッダ」と「ヘッダー」、「XML文書」と「XML文章」、「はてなID」と「はてなアカウントのid」などの表記ゆれ。document に対する訳語は通常は「文書」を用います
• 「～することができます」という冗長表現。私もよくやってしまうのですが、これは「～できる」にとした方がシンプルで読みやすくなります
• 「GETをリクエストする」と「リクエストXML文章をPOSTする」。これも表記ゆれの一種ですが、私だったら「GETする」「XML文書をPOSTする」にします
• 単純なコピペミスっぽいですが、下書きコレクションの段落で、「XXXXXXXXXXは実際には」で切れてしまっている文章がありました

こういった基本的な文章のバグは、ワードの文書校正ツールなどを使うと簡単に検出できるものも多いので、機械的に処理するのがおすすめです。

必須項目のチェック

次に、仕様書として必要な項目が足りているかを確認します。

基本設計仕様書やテスト仕様書など、フォーマットがある程度決っているものであれば、それに沿っているかをチェックします。今回の場合は Web API の仕様書なので、これが標準、というフォーマットはないと思いますが、以下の項目が足りないかなと思いました。

目次

仕様書は全体が長いので、さっと目を通せるように目次を入れる方がよいでしょう

エラー仕様

Web API の場合、エラー仕様というのはなかなか書きづらいのですが、それ
でも不正な操作に対して、API がどのように反応するかを一言記述しておく方
がよいと思います

セキュリティに関する考察

RFC などでは必須になっています

変更点、拡張点のチェック

AtomPub のように、ベースとなる仕様書があり、それに基づいた形でAPIを設計する場合は、オリジナルとの変更点や拡張点を明記する方がよいでしょう。逆に言うとオリジナルの方で詳しく記述されている部分は、概要だけを書いて詳細はオリジナルを参照してもらう方がよいと思います。

今回のAPI仕様でいえば、変更点は X-HATENA-PUBLISH ヘッダ、拡張点は hatena:syntax 要素になります。

オリジナルの仕様を変更した場合は、なぜそのような設計になったのか、その理由を書いておく方が親切です。特にある程度標準に従っている場合、利用者はオリジナルの方法に慣れているため、変更点はつまづきポイントになるからです。

この理由とはたとえば、レガシーシステムの実装上の都合であるとか、開発効率の問題であるとか、はたまたオリジナル仕様が間違っている、などが考えられます。残念ながら、現状のはてなダイアリーAtomPubの仕様では、なぜ AtomPub 標準の app:draft 要素ではなく X-HATENA-PUBLISH が必要だったのかの記述はありませんでした。

拡張点については、はてなダイアリーAtomPubの仕様では hatena:syntax 要素がはてな記法を入れるために導入されたことが明記されているので問題ありませんね。

技術的なチェック

最後に、技術的な正確性を検証します。

今回、私が気づいたものとしては以下の点があります。

• content/@type が text/html なのに、要素内容のタグがエスケープされていません(実装は正しくされています)
• パラメータ付きURIは URI Templates の記法を利用した方がよいでしょう(/はてなID/atom/draft/XXXXXXXXXX → /{はてなID}/atom/draft/{entry-id})
• HTTP/1.1 201 CREATED の Reason-Phrase は Created が一般的です(CREATEDでもHTTP仕様としては間違いではありません)

まとめ

技術文書にはプログラムだけでは伝えきれない設計の意図を伝えるという目的があります。プログラムもそうですが、文書もひとりで書くだけではなくレビューすることが大切です。人に読んでもらうことで初めてわかることも多々あるので、ソースコードレビューと同じくらいドキュメントのレビューにも力を入れるべきです。

また、文章の書き方自体の勉強も大切です。私も偉そうなことは言えないのですが、学生のころにかずさんの正確な文章の書き方を読んだり、檜山さん(プロのテクニカルライター)のライティングスキルを目の当たりにしたりして(参考)、技術者のライティングスキルの重要性を認識しました。

ということで、このエントリでライティングスキルもプログラミングスキルと同じくらい重要である、と認識してくれる人が増えることを願っています。

ちなみにこのレビューシリース、まだ続きます。