技術ブログアンチパターン - 「The Top Mistakes Technical Writers Make」

Last updated at 2021-08-09Posted at 2021-08-01

The Top Mistakes Technical Writers Make の記事の読書記録です。テクニカルライターと言いますがマニュアルや、仕様書などと言うよりは、いわゆる技術ブログに向けたポイントに見受けられます。

記事の要点

以下を意識して記事を改善しよう、というお話。
逆に表現するとライターが陥りやすいアンチパターンは、以下だという。

!! 記事の構成がない
- 記事をセクションに分ける。見出しをつけ、複数のパラグラフに分割する。
!! コードに画像を使ってしまう
- コードはスニペットやGist等を使用する。
!! 記事の長さ・短さを気にしてしまう
- 長過ぎるか、短すぎるか、字数にこだわる必要はない。まとめたいテーマと、問題解決に焦点を当てる。価値提供に集中する。
!! アプリケーションの紹介にデモがない
- コードは、読む人がそれを使用できるようにする。
!! 一文が長い
- 記事の流れを良くするために、長い文を複数の文に分割する。
!! 人に読まれるための対策をしていない
- 画像には代替テキストをつけるなど、人に記事が読まれるための対策をする。

それぞれのポイントについて見てみます。

ライティングを始めた頃、すべてのブログ記事を2000ワードにしようとしていた。ネット上で「長い記事の方が良い」と言われていたからだ。しかし、文字数を増やすためだけに記事を長くする必要はない。
500語で技術的な記事を書けるのであればそれが良い。言葉のノルマを達成するのではなく、新しい概念を説いたり、問題を解決したり、コンセプトを教えたりすることに集中しよう。
一方長い記事を書いてはいけないというわけではない。重要なのは、短い記事の中で問題を解決したり、コンセプトを教えたりできるのであれば、記事を長くするためにフワッとした要素を加える必要はないということ。
解決策
- 記事の長さは気にしない。価値を提供することに集中する。

アプリケーションの作り方を教える技術記事の多くで、デモを含んでいない。もしあなたがアプリケーションを作るためのチュートリアルを書くなら、Gitリポジトリを添付するとよい。人々がコードにアクセスできるようにしましょう。
解決策
- アプリケーションの動作を見ることができるデモを添付するのも良い。
- しかしいずれにしても、アプリケーションのコードを添付することをお勧めする。

長い技術論文。あなたはそのような文書に従うだろうか？
解決策
- 長い文は複数の文に分割し、1つの文章に1つのアイデアを残すようにする。2段落を占めるような文章は書かない。読んでいて混乱する。
- 短く、要点だけを伝える。

多くの記事中の画像に、代替テキストがない。なぜそれが重要なのかと疑問に思うかもしれない。
目の不自由な方のことを考えると良い。目の不自由な方は、画像の内容を理解するために代替テキストを頼りにする。
代替テキストはSEOにも欠かせません。人々がオンラインで何かを検索するとき、あなたの画像は関連性があれば検索結果に表示される。記事に画像を使用する際の3つのトップアドバイスは以下。
- 説明的な名前を使う。my_image.png 等の画像ではなく、それに応じた名前をつける。例えば、VS Codeのエディタが写っている画像であれば、visual-studio-code-editor-screenshot.pngのようにする。
- 代替テキストを使用して、画像が何を示しているかを説明する。VSCodeエディタを例にとると、This-is-an-image-of-my-VSCode-editor.png 等。
解決策
- 基本的なSEOのヒントを読んでみるのも良い。より包括的に改善することができる。

いわゆるテクニカルライティングという話ではないが「読み手を意識しよう」は間違いなく大事だと言えそう。

以上参考になればさいわいです。