仕様書

仕様書

[1] 仕様書 (specification) とは、何らかの対象の仕様を定めるものです。 仕様 (specification) とは、何らかの対象が満たすべき要件や性質の記述です。

仕様の性質

[2] 仕様には、広く世界中で実装される基準となるものもあれば、 唯一の製品についてのみ言及しているものもあります。広く実装されるものであれば、 相互運用性の向上のために対象を詳細に記述した仕様書が必要となりますが、 ごく限られた範囲でのみ用いられるものであれば、 特定の人の脳内にのみ仕様が記憶されていることもあります。

[3] 仕様を記述した仕様書が存在する場合、その体裁や内容も記述対象によって様々です。 多くの場合は何らかの自然言語による人間可読な文章として記述されていますが、 対象によっては機械可読な仕様記述言語によって記述されることもあります。

[4] 仕様書は、標準化団体による標準として出版されることや、 政府機関等による公的な文書として作成されることもあれば、 企業個人による私的な文書であることもあります。

仕様書の品質

[6] 仕様書の品質は、様々です。標準化団体標準仕様の場合、 その標準化手続きで定められた品質基準に沿ったものが出版されることになりますが、 その基準も様々です。

[7] 一般に「原案」よりも正式版が、古い版よりも改訂版が品質が高いことが多いですが、 一概には言えません。標準化団体ごとの色もあります。同じ標準化団体でも、 編集者ごとに様々なことがあります。

[8] 標準化団体の権威や歴史の長さと品質には、相関はなさそうです。 仕様書の長さと品質にも相関はなさそうです。

[9] JIS国家標準ですが、要約JISのように低品質の規格を量産する制度があります。

[10] 本文が短い仕様書は、短い分十分に検討されたものかもしれませんし、 細部を無視した結果短くなったのかもしれません。

仕様書の読み方

[11] HTML Standard ( 版) <https://html.spec.whatwg.org/#how-to-read-this-specification>

This specification should be read like all other specifications. First, it should be read cover-to-cover, multiple times. Then, it should be read backwards at least once. Then it should be read by picking random sections from the contents list and following all the cross-references.

この仕様書は、他の色々な仕様書と同じような方法で読むべきです。 まず、最初から最後まで、何度も繰り返し読むべきです。 次に、最低でも一度は、最後から最初まで逆向きに読むべきです。 加えて、目次から適当な章を選んで、そこにある相互参照をすべて辿って読むべきです

[12] という HTML Standard の(若干ネタ混じりの)規定は極端で、 実際にそんなことをしている人はほとんどいないでしょうが、 仕様書が記述する内容を理解するためにはとても重要です。 仕様書は初見で理解しやすく書くことよりも厳密に規定することをずっと重視して書かれていますから、 (もちろん意図的に難解に書いているわけではないでしょうが、) 流し読みでは正確に理解できる保証はまったくありません。

[13] 仕様書の翻訳は、読むべきではありません。特に Web などの進歩の早い分野では、日本語訳が存在すること自体が有害ですらあります。 ほとんどの日本語訳は、翻訳の品質が十分ではないか、十分であることの保証が何もありません。 しかも原文が改訂される速度に追いついていることもほとんどありません。 訳文は正しくないものとみなすのを原則とせざるを得ません。

[20] JISISO など海外の標準化団体仕様書日本語版を出版していることはありますが、 改訂への追随が数年遅れだったりするので、要注意です。 国家標準でありながら、分野によっては翻訳の質も微妙だったりします。

標準技術の仕様書の入手

[14] インターネットWeb に関する分野の標準技術の仕様書は、 Web 上で無料で入手できるのが一般的になってきました。

[15] 従来は標準化団体規格票紙媒体出版し、その販売標準化団体収益とするのが一般的でした。 規格票は高額で、一般書店でも流通せずその分野の専門家以外にはほとんど縁のないものでした。 今でもそのようなビジネスモデルを続けている古い標準化団体はあります。

[16] 古くからある大きな標準化団体では、 中央組織の意思と末端の標準化委員会の方針が食い違っていて、 末端委員会や編集者が独自に仕様書Web 上で無料で公開されていることもあります。 正式版を公開することに問題があって、実質的に正式版と同じ内容の最終案がかわりに公開されていることもあります。

仕様書に関する用語

高次の規定

[21]

仕様記述言語

メモ

[5] Hixie's Natural Log: Writing specifications: Kinds of statements ( 版) <http://ln.hixie.ch/?start=1140242962&count=1>

[17] [tech] プログラムが書けない人に「仕様変更」について説明するには | Fri, Mar 1. 2013 - 氾濫原 [HANRANGEN] ( ( 版)) <http://lowreal.net/2013/03/01/4>

[18] schematron.com » ISO Schematron 2016 Released! () <http://schematron.com/2016/11/iso-schematron-2016-released/>

The stan­dard’s body is only 14 pages, and 20 pages annexes.

[19] 仕様書の短さを誇っているところには、独特の感性が感じられます。 仕様書は短ければいいとか長ければいいとかいうものではなく、 記述する対象の相互運用性の実現に必要十分な内容があることが望ましいと思うのですが。