先日行われたQiita Engineer Festa 2023の締めイベントOnline Meetupにて登壇させていただいたので、その時の発表資料を公開させていただきます。

スライド↓

本記事で伝えたいこと

「 面白い記事 」から出発して「万人受けする記事」に近づけるのが良い
冒頭で工夫をすると良い
再現性 を意識してソースコードや環境を記載するのが良い

記事自体は当時の発表内容を元に、時間の都合上話せなかったことも追記しまとめました、参考になれば幸いです！

自己紹介

株式会社ゆめみに24卒で入社予定のnamniumと申します！現在は大学院生です。

最近はTauriという、RustとTypeScriptでデスクトップアプリケーションを作れるフレームワークを用いて、自己満足なアプリを作るのが趣味です！

Qiita Engineer Festaで投稿した記事

Festa期間中は4本の記事を投稿しました！

上司「オンプレでチャットAI作って」
- ChatGPTがない環境でもLLMを動かせないかを、rinnaモデルを触り検証した記事です！
【全CLIアプリGUI化計画】TauriでTypeScriptやRustからCLIアプリを呼び出す
- 上記オンプレGPT記事の続きで、CLIで作ったアプリをTauriに組み込み、GUI化させる方法について書きました。
ChatGPT先生のお陰でネットワークスペシャリストに合格した話
- 資格試験勉強にChatGPTを使ったので、その知見をまとめた記事になります。
「Reactでawaitしたら壊れた」「Reactでawaitしたら壊れた」～ useEffectの誤用と2回実行～
- Tauri開発を通じて知ったReactのuseEffectに関する注意点について書きました。 RustとTypeScriptがペアプロする小説です！

自分で言うのもなんですが、ChatGPT以外の記事はどれも尖った記事だと思います。特に4つ目は小説という人を選ぶような記事です()

方向性: どんな記事にするか？

どっちの記事がいい？

まず、どういう記事を書くかで迷いました。

Qiitaでバズるような記事には色々ありますが、とりあえず次の2つだと思います。

一つは、「万人受けする記事」で、

ReactやChatGPTみたいな流行っている技術に関してで
極力技術的な話題のみを正しく、わかりやすく、簡潔に

書いた記事になります。

もう一方は、「面白い記事」で、

他のエンジニアは知らないような自分だけの話で
なるべく濃くて、ストーリーや読み応えがある、詳細に

書かれた記事です。

万人受けする記事は、「コミュニティに貢献したい」みたいな利他的な感情から生まれるものですが、シンプル故に難しそう、公式ドキュメントには勝てないんじゃないか、という不安があります。

一方で、面白い記事は、「自分の好きな考え・技術を広めたい」みたいな利己的な感情から生まれるものですが、尖りすぎていて受け入れられないんじゃないか、という不安があります。

悩みました。

面白い記事がいい！

じゃあ自分はどちらがいいかなと考えたのですが、百合小説みたいな尖った記事を投稿したことからわかるように、面白い方を取りました！

理由としては、どちらの記事を書いても「ウケない不安」があるためです。具体的には、全然いいねがつかず、トレンドには乗れず、すぐに記事が埋もれてしまう可能性がどんな場合でもあります。

そこで、 最初から「ウケなかった時」を考える ことにしました。

そうすると、「万人受けする記事」は(あくまでも自分の場合はですが)、「ウケること」を目的として書いているので、落ち込むだけで何も得られません。

一方自分が面白いと思って書いた記事は、同じくウケ狙いではあるのですが、ウケなくても「自分と世間の感覚がズレていたのが原因だ」と納得できるメリットがあります。

セルフ・ハンディキャッピングという考えです。例えば試験前にわざとゲームをしたりして「ゲームしたから試験で悪い点数を取った」と言い訳するのもこれです。ここではこの考えを逆手に取っています。

それに、大衆にはウケなくても、自分が書きたいことを書いているので 自分という読者には刺さる というメリットがあります！

なので「面白い記事」を書くことにしました！

面白い記事 ⇒ 万人受けする記事

自分を想定読者にした記事ならウケなくても意味の残る記事になりそうです。

だから、RustとTSの小説みたいな、「自分が面白いと思う記事」を書くことに決めました。書きたいことを書いているのでモチベを維持するのも容易です。とりあえず 出発点 として「面白い記事」から始めることにしました。

しかし、最近のQiitaについてSNSでは「ポエムは投稿しないで¹！」や「もっと読み手に配慮してほしい」といった声を聞きますし(つまり本記事みたいなのが減ってほしいということなのでしょう...)、記事によっては読者として私もそう感じる時があります。

ですから執筆者として、そういう世間とのズレは、「自分からのツッコミ」で是正することにしました！「ポエムしすぎていないか、他の人が読んで辛いものになっていないか」みたいに自分で自分に突っ込みます！

つまり「正しい記事を書きたい」「わかりやすい記事を書きたい」という自身の欲求を自浄作用にして、 「万人受けする記事」に寄せていく 、という風に記事を書くことにしました。

これならばモチベも維持できて無理のない執筆ができます。できることから一歩ずつ寄せていきます。

工夫: どう読ませるか？

前節までで、「そもそもバズらなくてもいい」ように記事を書く、と決めましたから、バズるための工夫はいらないかもしれません。

それでも、読みやすい記事を書くため・記事に訪れてくれた人からいいねをもらうために、やはり何かしらの工夫が必要です。

本節「工夫」と次節「正当性・再現性」の残りの2節では、主にその話をします。

記事の要: 冒頭

工夫として本記事で特に解説するのは冒頭についてのみです。

なぜなら、読者は最初の数行で最後まで読むブラウザバックするか決めるからです！

最初に書く内容がすべてを決めます！

...

というのは流石に言いすぎですが、それぐらいに重要なので、

冒頭を工夫することで 読者が続きを読まざるを得ない状況を作る ことを意識しました。

方法は色々ありますが、自分が意識している

自己紹介や前提の記載
TL;DRやまとめ
成果の強調

の3つを紹介したいと思います。全部行う必要はなく、どれかができていると良いでしょう。

自己紹介・前提の記載

1つ目は自己紹介や前提の記載です。

「この記事は読者あなたのニーズを満たしていますよ」ということを示す効果があります。

例えば肩書だけでもかなりの効果があります。

「新卒です。読んだ本を紹介」みたいな軽い自己紹介があるだけで、「この記事は新卒レベルの人でも読めるんだ」ということが伝わり、敷居が低くなります。高校生とか他の肩書きでも同様です。大ベテランの方なら逆に「すごいことが書いてあるかも」と期待させる効果があります。

他にも、「最新情報をまとめた」のように、記事の特徴を最初に軽くまとめるだけで、読者に記事を読ませる動機を作ることができます。

特に書くことがない場合でも、アカウント名で自己紹介をすると、次に投稿した時に「あの記事を書いた人だ」となりブランディングが狙えます。

TL;DRやまとめの記載

2つ目はTL;DR(トゥーロング、ドントリード、長すぎるから読んでいない)やまとめの記載です。

本記事の冒頭に載せているまとめが例になります。以下再掲↓

本記事で伝えたいこと

「 面白い記事 」から出発して「万人受けする記事」に近づけるのが良い
冒頭で工夫をすると良い
再現性 を意識してソースコードや環境を記載するのが良い

もったいぶらずに最初に結論を書いてしまいましょう。最初しか読んでもらえないなら最初に伝えてしまおう という逆転の発想です。

最後まで読んでくれる読者にもメリットがちゃんとあり、 結論を知っているので安心して読めます 。「中盤まで読まないと自分に必要な情報かわからない」という不安がなくなり、より読んでもらいやすくなります。

最初にテーマが固定されてしまうので、 ブレにくく、一貫した内容が書ける ようになる、という執筆者にとってのメリットもあります。

成果の強調

3つ目は成果の強調です。 してやったんだぞ 感を出して読者に衝撃、インプレッションを与えましょう！イメージとしては論文の最初のContributionsみたいな感じです。やったことを全面に押し出します。

私は「何かのアプリを作った → アプリ紹介」という流れでQiita記事を書くことが多いのですが、このパターンの時に特に有効な方法です。

成果をしっかり載せることで、「動くコードが載っている」証明になったりと、記事の質の担保となる効果もあります。

成果物配置の例

私の場合は大体、本記事でSpeaker Deckの埋め込みスライドがあるようなぐらいの位置に、次のように配置しています。

リンクの記載

コンテンツを一番理解してもらえるページへのリンクです。なるべく Webアプリにする と理解してもらいやすいです。

ただ、リンク先で何をされるかわからない不安より、押してはもらいにくいかもしれません。

アイキャッチの掲載

インプレッションの主役です。成果物の存在を嫌でも認知させることができます。

写真か、できれば自動再生される gif画像 が効果的です。

gif画像以外の動画も悪くはないのですが、

自動再生されない
再生すると 音が鳴るかもしれない と不安にさせる

というデメリットがあるので、私は掲載したことがないです。

一方gif画像自体も容量が大きくなりがちなので、どう掲載するかはケースバイケースだと思います²。

リポジトリの記載

記事の質の担保になる部分です。記事に掲載しきれないコンテンツのソースコードを載せるにはやはりGitHubリンクが一番です！

GitHubリンクとわかっているので上のコンテンツのリンクよりは押してもらいやすいかと思います。

正当性・再現性: どうあるべきか？

記事の正当性・再現性は、ここまでとは異なり減点方式的な考え方です。「違和感のない・悪くない記事」と読者に思ってもらうために必要です。

正しい記事を書く

どんなに良い内容が書かれていても、不自然な点があるといいねしにくくなります。できる範囲で気をつけることが大切です。

特に自分は、

用語・概念を間違って書いていないか
情報が新しいか
ソースコードが正しいか・おま環ではないか

を気をつけています。1は正しいかに関わり、2と3は再現できるかに関わります。順に解説します。

概念・用語を正しく

よく言われることですが、解説する内容はできるだけ1次ソースをあたるようにします。執筆のしやすさのために、作業段階からURLをソースコードに残したりすると捗ります。

また、丁寧に記事を書いている証拠として、技術用語だけではなく理解が怪しそうな言葉はなるべく調べましょう。

とは言っても概念・用語の間違いはいくら気をつけても直しきれるものではありません。あまりにもひどければコメントをもらえるでしょうし、自分でできる範囲で気をつけていれば問題ないです。

執筆時期を正しく

記事の日付はQiitaが自動更新してくれるため問題有りませんが、

関係するソフトウェアの バージョン は極力表記しましょう。

記事が最新かは読者が最も気にする点の一つです。執筆時点で最新版のツール・アプリ・言語を使っているならば、はっきりと分かる場所にそのことを記載しておきましょう。

またバージョンは古いからといって悪いわけでは決してありません。理由があって古いバージョンの情報を探している人もいるためです。バージョンの記載さえあれば、最新版とは異なる挙動が書かれていても不審には思われなくなります。

ソースコードを正しく

最後にソースコードについてです。動かないコードがあると記事の信憑性がだだ下がりするので、 最低限動かして確認しましょう 。

詳しい人なら間違ったコードはすぐ見抜けるので、擬似コードだったり省略して書く場合も、対応する動くコードで検証するべきです。

(何故実行確認しようとわざわざ言うかというと、初心者から上級者まで、意外と確認していない記事が多いためです...)

そして おま環 (お前の環境じゃないと実行できないけど³)を避けましょう。

同じ言語・バージョンでも動くとは限らないため、どういう環境であるかと、余裕があれば環境構築についても記載するべきです。分野によってはCPUアーキテクチャやハードウェア等低レイヤーについても言及するべきでしょう。

発展: 仮想環境

ここまでやらなくても良いですが、DockerやVirtualBoxといった仮想環境を使用して検証までできると完璧です。次のメリットがあります。

おま環に 気付ける : 例えば build-essential みたいな「大昔入れてて当たり前になっていたけど実は必要だった依存」も、仮想環境なら赤裸々に暴きます！
Dockerfileで 残せる : そもそもDockerfileは再現性を担保するためにあります(要出典)。Dockerfileは 実行できる備忘録 です。書き残してあれば記事執筆段階で大いに役立ちます。

Dockerでなくとも、1つ目だけでも大きなメリットです。最近私はWindowsを基準に記事を書くことが多いので、Windows向けにProxmoxサーバーを構築中です。

仮想環境でないにせよ、記事に書かれた内容が まっさらなところから (前提部分まで構築して) 実行できること を確認できるとベストでしょう。

成果物記載の話や再現性に関する話は、以前私が書いた記事にて詳しく解説していますので、さらに気になった方は読んでいただけると幸いです。

Qiitaでズルく「いいね」を稼ぐ方法またはQiita駆動開発者の戯言的な何か - Qiita

まとめ

記事投稿で意識していることを話しました！

方向性: 面白い記事 を起点に、自浄作用で万人受けする記事に寄せる
工夫: 冒頭で読者を掴む
正当性・再現性: 読み手に気を遣い、特に 再現性 を意識

ここまで色々話しましたが、人によって記事の書き方は千差万別だと思います。

ありふれた結論ですが、 楽しく 記事を書き試行回数を稼いで、自分なりの書き方を見つけるのがベストじゃないかなと思います。

所感

「まとめ」までがOnline Meetupで話した内容になります。参考になったでしょうか？

普段は最初から記事にするので、スライドから記事に起こしたのは初めてですが、セリフ、呼びかけばかりなため単調な記事になってしまい、記事とスライドという媒体間の良し悪しがついでにわかった気がします。今後はスライドも上手に作れるようになりたいです。

ここまで読んでいただき誠にありがとうございました！

前節にも絡みますが、Qiitaはポエムを含めて様々な記事が投稿できるコミュニティになってきているので、情報を探す読み手側にはノイズが多い媒体になってしまっているものの、現状書き手には優しい媒体になんじゃないかと思います。実際、執筆キャンペーン等が活発に行われている印象です。⇐ どこかに書きたかったけど書けなかったので脚注に書いたポエム ↩
gifに変わる自動再生機能付き音無し動画フォーマットで良いものが出てほしいですが、gifより作成が容易でQiitaに掲載しやすいものというのを私はまだ見つけられていないです...誰か情報をまとめてくれると私が喜びます。 ↩
本来は問題が起きている時の「お前の環境だけ」の略ですが、インパクトの強い単語なので本記事で使わせていただいております。 ↩

【OnlineMeetup登壇資料】記事投稿の葛藤