説明と内容の分離
仕事でAWSの設計書書いてて、「このテンプレを育てていく方針だからこれ埋める形で書け」制約も課されているのだけれど、まあそれはともかく
一つ気になったのが「説明」と「内容」が混在していること
たとえばAWS ELB（ロードバランサー）の設計パートで、クロスゾーン負荷分散をどうするかという項があるんだけど、ここでクロスゾーン負荷分散自体の説明が入っているsta.icon*2 要らなくない？
そういうのは事前に知っている前提でいいだろう
AWSの正式用語なんだし
カジュアルなドキュメント（特に新人などにも想定したオンボーディング機能も持つもの）なら別にいいけど、違うんだよなsta.icon
train.icon
最初そういうの書いててカジュアルすぎて一蹴されて、現行踏襲でちゃんとしたの使おうって出てきたのがこれ なのにさ、説明も安易に入れてるというｇｄｇｄぶりなわけです
そしてこういうメタな話が通じる相手でもない
説明は知ってる前提にするか、そこまで期待するのが厳しいのであれば「説明用のドキュメントを別途つくれば」いいだろう
別にドキュメントである必要もない
ScrapboxみたいなWikiやHTMLでもいい
こういうちゃんと分けようって以前なんかマトリックスで見たよな
読む
oriented
チュートリアルは learning oriented
ガイドは goal oriented
説明は understanding oriented
リファレンスは information oriented
そうそう、これこれ
GitLab社も参考にしてるらしいんだけどsta.icon
今回つくってる設計書は、ここで言えばガチのリファレンスなんだよな
なのに説明が混ざっている