こんにちは、Watanabeです。
先日のRails appの記事は結構長くて書くのが大変で、途中でRubyのバージョンアップに失敗したからそちらの記事を書き始めたりと、何日かにわたる大作になってしまいました。
「大作志向だといつか記事を書ききれなくてお蔵入りになるよなー、というか現職ではそういうことがちょくちょくあるなー」と思いまして技術記事をコンパクトにかけないかなと思案しています。
技術記事には何が必要なのか
結局、技術記事には何がコアとして必要で、なにが不要なのかっていうのは深く考えたことがなかった気がする。
プログラミング中につまったことであったり、課題的なところをビフォーアフターで示す。
↓
技術的な理屈を解説する
ぐらいに考えていましたが、調べてみるといい線いってるみたいですね。
ミノ駆動さんが書かれた技術記事の書き方の記事に行き着きました。
タイトル
概要
この記事で伝えたいこと ←★重要★
解決したい課題 ←★重要★
課題の原因
課題を解決する技術、手法
技術、手法の概要
技術、手法の効果
課題がどう解決されるか
応用事例のカタログ化
留意点、デメリット
記事から引っ張ってきましたが、おおよそ私が考えていた方向性で肉付けがされている印象です。
解決したい課題を重要視するのは、業務でライティングしていたので共感がありますね。記事のコアがここになると思います。
ここの課題感が広く沢山の人が悩んでいるもので、記事がうまいことその課題を解決するなら、よく見られる記事になるんでしょう。
コンパクトな技術記事を書くには
記事内容の方向性に問題がなかったので、あとは「記事に取り上げる課題のスコープ」が広いか狭いかの問題でしょう。
この前のRails app のアップグレードは
これら3点を中心に周辺情報がいろいろあってスコープがかなり広かったように思います。
これを「gemのアップグレード」に絞れば記事はコンパクトに書けそうです。
作業の範囲ではなくて「課題のスコープ」を意識するのが重要ですね。
