仕様書の悩み
たまにはIT系の仕事してる風な話をしようと思います。笑
最近、コード書くより設計書、さらには仕様書を書くことがほとんどです。
お客さんと話して、要件整理した後、要件定義して、仕様をつくっていくわけですけども、誰もが悩むであろう仕様書や設計書のドキュメントづくりに苦しんでいました。
マークダウンとかYamlでいい感じにかけて、いい感じに整形してくれるもの。。。
ありました！
その名も redoc https://github.com/Redocly/redoc
流行りのSwagger/OpenAPI
API仕様書をSwagger/OpenAPIで書こうっていうのは、結構前から言われていて、長いこと流行ってますね。
エンジニア大好きYaml形式でかけて、ドキュメント管理がしやすい。
Git管理できるって結構良い。たすかる。
ただ、私も乗っかってみたものの。。。どう書くのが正解なのかわからず、書き方がいっこうに身につかない。
API仕様書の良い例を見つけた
そんなときに見つけたのが、anglcamの仕様書 https://developers.angelcam.com/ です。
仕様書とはこう書けばよいのかと。
AWSとかGoogleの仕様書を見てきましたが、あれはバカでかいサービスを細かに説明してくれてるので、規模が違いすぎてあまり参考にならず。。基本的な書き方はとても見本になるんですけれどもね。
ということで、仕様書は anglcam を参考に書くことに決めて、一心不乱に書き連ねたら結構良いものができ、同僚にも見やすいという評価を得ました。
記法に沿って書くのはかけるんですけど、最初のほうの基本的な説明部分ですよね。
ここが難しい。
適当に書けばわかりづらくなるし、細かく書いたら読みづらい。
仕様書とはこれくらいのゆるさでよいのかと、良い意味で力を抜いてかけるようになりました。
案件にもよりますが、これでOKって言ってくれるお客さんには積極的に使っていこうと思います。
今日も散文失礼いたしました。