設計原則・パラダイムとテクニカルライティングの共通点を見出してみる

対象読者

• これから技術的な記事を書こうとしている人

• 技術的な記事の文章構成に迷っている人

この記事を読む前に

テクニカルライティングのベストプラクティスはGoogleのテクニカルライティング資料にまとまっていると考えています。

有志による翻訳もありますが、まともに読もうとするとそれなりの時間がかかります。

要約(Summary of Technical Writing One)を見るだけでも文章を書く上で必要とされる原則は把握できると思うのでそこだけでも一読する価値はあると考えてます。

忙しい人向けまとめ

• 読者＝アクター＝audienceを意識して執筆する

• ステートレスな文章を心がける。手続き的な文章は控える。

• ソフトウェアと文章は性質が違うが、ソフトウェア開発における原理原則やパラダイムとテクニカルライティングには共通点が見いだせる

• 可読性を高めることおよびチーム開発に貢献する原理原則は転用できそう

この記事を書いた動機

• コードを書く以外にもソフトウェア開発者としての実務では自然言語で文章を書いてやりとりを行うことがかなり多いと認識した

• 筆者の実務において最近の開発のテーマは良い設計やコードの品質。そんな経験を通じて会得した設計およびプログラミングのパラダイム・諸原則がある。

• こうした諸原則はコーディングだけでなく文章を書く際にも役立てることができるのではないか、と考えた。

• 筆者が継続的な技術的知見のアウトプットを実現するためのlinterとなるような記事を残したい

読者(アクター)を絞り、一貫させること

Google のテクニカルライティングのサマリーにも書かれていることですが、技術記事などまとまった分量の文章を書く際には対象読者を明確にすることが大事とされています。

ここでいう対象読者というのは読者のテクニカルなスキルだけを指しているのではなく、読者と筆者のコンテキストを可能な限り近付けることが大事と考えています。

たとえばプロジェクトの背景に強く依存している技術採用経緯など、コンテキストを明示あるいは読者に合わせて不要なコンテキストを削ることで読みやすさにつながると考えています。

副次的な効果ですが、筋違いな意見を抑止することも可能になると考えています。(例：批評を読んだとき、それができるならとっくにしているんだよなぁ的なモヤモヤを防げる)

関連するプログラミングパラダイム/設計原則: SRP(単一責任の原則)

同じソフトウェアモジュール(記事)を異なるアクター(読者)に利用されることを防止する、という考え方はソフトウェア開発と記事執筆において共通していると考えて良さそうです。

見出しには要約、あるいは疑問形を駆使すること

多くの技術記事がある中で自分の記事を読んでもらうためには見出しを工夫することも効果的です。

記事を一語一句読まれるわけではなく、流し読みされることも多々あるので忙しい人向けに見出しを工夫することも大事です。

例

• ドメイン駆動開発を効果的に導入するにはユビキタス言語を定義すべき

• ドメイン駆動開発を導入すると何がうれしいのか

疑問形にすることで、読み手は答えを念頭に記事を読むことができ、書き手は質問と答えというフレームワークを念頭に記事を書くことができて効果的です。

関連するプログラミングパラダイム/設計原則: TDD(テスト駆動開発)

プログラミングパラダイムというよりは設計技法ですね。

実際に記事を執筆していると、見出しと実際のセクションの内容の乖離が往々にして発生します。

その際は、TDD(テスト駆動開発)ならぬ見出し駆動ライティングという考えを持ち、見出しを作り伝えたいことを構成すると良いと考えています。

読者にステート(状態)を持たせないこと

ステートレスあるいはイベントソーシングという考えがソフトウェアの世界にはありますが、これは記事執筆にも言えることだと考えています。

読者自身が文章で大事そうな所を見出しつつ文章全体の構成を把握しなければならない、という記事になってしまうとその記事で伝えたいことを正しく伝えられない可能性があります。

このことは大学入試の現代文の問題をイメージされるとわかりやすいかと思います。

すでに述べたような見出しの工夫や対象読者を明確にすることを心がけたり、Cognitive Conplexityの高いような文章を控えることが大事です。

終わりに:共通点はある、まだ見えていない

そもそもソースコードは人間とコンピュータという2つアクターから解釈される一方、文章は(自然言語解析などのケースを除くと)人間にしか解釈されません。

そして、設計の原則やパラダイムは人間にとっての可読性を高めることだけが目的ではなく「変更に対して強くなること」という側面が大きいですが、果たして文章において変更に強いこととは何なのでしょうか。そもそもそれが求められているのでしょうか。

この記事を書き上げた時点ではコーディングとテクニカルライティングの共通点を昇華させ、汎用的な原則を得るには至りませんでしたが、
探求していきたいと考えています。