社内の LT 会で発表したものになります。
概要
本記事は、技術記事を読む人の視点について考え、より多くのエンジニアが技術記事の執筆に参加しやすくなるヒントを共有します。
はじめに
テレビショッピングで掃除機を買いたくなるのはなぜでしょうか？
（買いたくなるかどうかは人によります）
値段が安いから、掃除機が魅力的に見えたから、衝動買い、などなど…様々ありますが、一説に
🛒 掃除機が「テレビショッピングを見る人の視点」で紹介されているから
という考えがあります。
また、水族館に来てマグロを食べたくならないのはなぜか？という問いに対し、
🐟 水族館が「マグロを育てている海の視点」で作られているから
という考えがあります。
このような、テレビショッピングにおける「利用者の視点」やマグロにおける「制作者の視点」を、技術記事でも考えてみます。
技術記事の視点
ここでは、技術記事によって触れられる話題を、以下の 3 つの視点に分類してみます。
記事タイトルの例も挙げてみます。
利用者の視点（ユーザー視点）
開発ツールの使い方や、エラーの対処法
- Cloudflare でキャッシュパージする方法
- ValueError: Single '{' encountered in format string
制作者の視点（ベンダー視点）
システムの設計・運用方法や、開発ツールの詳しい仕様
- Microsoft Intune を使って開発者向け PC のインストールアプリを統括的に管理する
- Miro の付箋の個体差について
どちらにも属さない視点（エクスペリエンス視点）
学習経験の共有や、体験談
- Ansible で Windows PC の開発環境構築を自動化した話
- ブラウザの開発者ツールで家庭用ごみ袋の外装を作った
同じ技術でも書き方によって視点が変わる
Python だからユーザー視点とか、Zabbix だからベンダー視点とか、使う技術によって視点が決まるわけではありません。
技術が同じでも、書き方を変えることによって視点が変わります。
Python の例
ユーザー視点
- 具体的な手法
- すぐに使えるコード
Python で文字列をカンマで区切って配列するには split を使います。
受け取った入力の先頭や末尾にスペースが入っていることもあるので、split する前に strip で両端のスペースを除去するのがおすすめです。
columns = row.strip().split(',')
ベンダー視点
- クラスの詳しい仕様
- 必要に応じてコードでの説明
IntEnum クラスは Enum の一種ですが、同時に int としての性質も持つため、int と IntEnum を == 演算子によって比較できます。
class FruitPrice(IntEnum):
APPLE = 100
BANANA = 200
FruitPrice.APPLE == 100 # results True
FruitPrice.BANANA > 500 # results False
エクスペリエンス視点
- 言語を使ってみての体験談
- 人生で役に立ったこと
私が思う Python の好きなところは、コードを英語っぽく書けて、コーディング面接で非エンジニアの面接官への説明がしやすいところです。
人への説明が得意でない私を救ってくれたのは、ほかでもないこの Python です。
Python マジラブ💛
テクニカルライティングの例
ユーザー視点
- 説明そのものを端的に記述
- 例文でイメージを持たせる
説明文は、あいまいな表現を避け、短くわかりやすく書きましょう。
「このボタンをクリックすると、ファイルシステム上のあらかじめ指定していたディレクトリにファイルが作成され、編集中の内容が書き込まれ、そしてまた閲覧したいときにいつでも閲覧することができるでしょう。」
→「保存するには【保存】をクリックします。」
ベンダー視点
- 詳しく知りたい人・極めたい人向き
- もはやこれがマニュアルでは？
テクニカルライティング（Technical Writing）は、技術的な情報をわかりやすく整理し、対象読者に伝えるためのライティング技術です。主に以下のような文書が含まれます。
- マニュアル・取扱説明書
- ヘルプドキュメント
- 技術仕様書・設計書
- API ドキュメント
- ホワイトペーパー
（ChatGPT の回答を抜粋）
エクスペリエンス視点
- 活用事例の紹介
- 魅力を伝える
社内でテクニカルライティングに関する研修を行い、翌日から業務で実践してもらったところ、実に 92 % の社員から「コミュニケーションロスが減った」「上司に褒められた」などの前向きでうれしい声が続出。
また、開発の生産性も研修前と比較して 28 % アップし、 “研修のこうかはばつぐん” だ。
まとめ
今回ご紹介した 3 つの視点は、私が日々記事を読んでいて面白そうだなと思った観点を言語化してみただけであり、各視点に良し悪しはありません。
どの視点で記事を書いても、読む人への効果があり、歓迎されるので、「書いてもどうせ読んでもらえない」などと心配する必要はありません。
私自身、
- ユーザー視点の記事は、すぐに使えるものが多く実用的
- ベンダー視点の記事は、もっと深く知りたい、人に教えたい、ツールそのものの開発に携わりたい人におすすめ
- エクスペリエンス視点の記事は、見ず知らずの人をその技術・ツールに誘う効果あり、もしくは読んでいて楽しい
と考えています。
また、この 3 視点をなんとなくでも知っていることで、記事を書く目的や記事を読んでほしい人物像が明確になり、記事が書きやすくなります。
もし、あなたが記事を書こうとしていて「何を書いたらいいかわからない」と悩んでいたら、ぜひ今回ご紹介した観点を参考にしてみてください。
みんなでたくさん記事を書いて、エンジニアのプレゼンスを高めていきましょう。