2023-11-07
ドキュメントを読むときに参考文献が適切に使われていないと辛い。ドキュメントには2種類あると思っている。
- 水先案内
- 主張をするドキュメント
主張をするタイプのドキュメントで参照先を読まないと主張を理解できない場合は辛い、というのが今回の主張。
水先案内のドキュメントとしては、wikipediaの水先案内ページやgoogle検索の結果ページが該当する。水先案内のドキュメント自体は主張をしておらず、その水先案内ページに辿り着いた読者が適切なドキュメントにたどり着くためのサポートをする役割を持つ。
主張をするドキュメントとしては、この記事やAPIの仕様を説明するページなどが該当する。参考文献とか例を上げる目的で引用とか他のドキュメントへの参照を持つことはあるけれでも、そのドキュメントを全く読まないでも主張を理解できることが期待される。もしも読まないと理解できないのであれば、その文章は主張をできていないんじゃないかと思う。サーベイ論文は主張をするドキュメントだと思う。参照を探す目的で使うこともできるけど、対象をサーベイしてこういう歴史があるとか界隈はこういう感じになっているよねといった主張をすることが目的なはずなので。論文のアーカイブページは水先案内。
ドキュメントはそれ自体で完結していて欲しいので、参照先に主張の内容が書かれているはドキュメントとして不十分で読むのが辛い。内容ではなく根拠を委譲するのは良いし、よくある引用のスタイルだと思う。