ソフトウェア開発201の鉄則 原理33:一般:どの文書にも用語集が必要だ

要旨

* ソフトウェア工学の世界には、すぐに理解できない、専門用語がたくさんある
* そのような専門用語の解説がある「用語集」を必ず文書に儲けよう
* 用語の定義は、「調べる手間を最小」とするように書くべきである
* 「可能な限り一般用語を使う」「説明が必要な用語は文中でイタリック体で示す」といったことが挙げられる

解説

文書に限った話ではない。他の工学の分野と同様、ソフトウェアの世界にも、その世界に精通しているものだけがわかる用語が、たくさんある。

そして、すごい勢いで進化している世界なので、次々と新しい用語、もっというと、同じ概念を言い換えただけの新しい言葉が、次々と出てくる。

出てくること自体は、工学といった専門分野、そして急速な勢いで進化している分野であるソフトウェアの世界の宿命といっていい。

では、このような専門用語を、どう扱うか。

大抵のソフトウェア用語用語がわかる専門家が、それがわからない相手に対して始めるのは、「解説」ではなかろうか。その意味を丁寧に説明し始めて、それで親切心を発揮している、と思っているエンジニア、多いだろう。

違う。

まず先にやるべきは、

「そんな用語を使わずとも一般用語、相手に通じる用語を使うことを考える」

だろう。

もっとも、一言で一般用語で置き換える説明するのが難しいものも、あるだろう。そういう時は、簡潔に、例えで「要は、XXX の世界のYYYのようなもの」と言えれると、相手に伝わりやすい。

とにかく、「相手にわかる」ということを優先させよう。

そのマインドさえ持っていれば、この原理で言っていることは、わかるだろう。

まず、必要のない専門用語を使わない。その上で、どうしても解説が必要な用語は、そうだとわかるようにしておく。その上で、文書の最後に丁寧な解説をつける。

実際にそこまで出来るかは、費やせる工数次第だが、意識だけは、しておこう。