nariのエンジニアリング備忘録

SRE/Devops/AWS/自動化/IaC/Terraform/Go/DDD など

読まれやすい文書を書く/継続して記事を書くコツ

技術発信のススメ

はじめに

どうもお久しぶりです。fukubakaことnariです。

7月に、技術発信を評価され、社内表彰していただきました！(そこからも必ず週１のQiita投稿はキープできている)

その際のfeedbackのなかで、 「どのようなことを意識して記事を書いているのか」 という質問がありまして、Qiitaの限定公開の社内のみで共有していたものをはてブで社外にも共有しようと思い、こちらにも転載しております。

非常に簡易なものですが、どなたかのお役に立てれば幸いです。

読まれやすい文書を書く３つの方法

1.まず大枠のプロット(目次)を打ってから書き始める

## TL;DR
## はじめに
## そもそもxxって？
## どんな人にxxはおすすめか(リコメンドじゃないなら想定読者とかでもok)
## なぜxxをしようと思ったか
## どうxxしたか
### 1.yyyy
### 2.xxxx
### 3.zzzzz
## 終わりに

2.結局5W1Hが重要なので意識して書く

WHOM

  • 誰に向けた記事なのか明記す

WHAT

  • 作った系ならまず何を作ったかを出す
  • 長くなりそうならTL;DR(Too long; didn't read.)を要旨として最初に書く
  • 取り扱うトピックについて、そもそもの説明は最初にサクッと入れる(間口を広げる)(ex:そもそもAWSアーキテクトって？ CIって？)

WHY

  • なぜ作ったか、そうしたか、記事を書いているかはなるべく書く

WHEN

  • いつ時点の情報なのかを意識してかいておく(後日訂正の時は特に)
  • 時間軸を意識する　過去の話、今の話、未来の話
  • 未来の話はできれば入れる 今後どう発展させていくか、fixするか

WHRER

  • どういうシーン、どこで起きたことなのかをできれば書く これはおまけ

HOW

  • HowはStepsに分けて書く(ex:1.手を洗う 2.材料をきる 3.鍋にぶち込む)

3.図を多用する

  • 必ず1枚でいいので入れると読者が読みやすくなる
  • draw.io なんかでシステム関係図を起こして載せる
  • マインドマップで事象の紐付きを整理して掲載

継続して記事を書くコツ

  • 完璧主義をやめる　不完全なものをまず出してから、ブラッシュアップしていくスタンスへシフト
  • 自分の思考を整理することになり、feedbackをもらうチャンスになるため、結局自分が得することを知る
  • 一回かいてみて、誰か一人の役に立つだけで嬉しいことを知る
  • とりあえずを増やす　ex:だるいけど、とりあえずプロットだけ打とう