投稿日

初めての「技術ブログ」書き方のご紹介

技術ブログは「書く」というより「記す」というのがシックリきている、ソラコム松下(max)です

2017年3月にテック・エバとして活動を開始し、通算400回以上講演の他、ブログでも情報発信しています。
年間で20本以上のブログを書いてくるうちに、だんだんと書き方がわかってきました。ですので、今回は 技術ブログの書き方ブログ を紹介します！

技術ブログは「未来の自分へのドキュメント」

技術ブログは普通のブログとは異なります。
未来の自分へのドキュメント です。

「あー、これ既にやったことあるなー。なんだっけ？」とググった先が自分のブログであってほしい、そんな思いで書いてみてください。一番最初の利用者が自分、すなわちドッグフーディングしましょう。これはサービス開発でも、ブログでも共通して言えることです。

もし、手元に「メモ的なテキスト」があるならば、それはブログにできるかもしれません。

まずはタイトル付け

改めて技術ブログの構成を見てみると、実はタイトルと中身だけです。この二つをサクっとできるようになると、いつでもブログを書くことができますので、マスターしましょう。

ブログ全般に言えることですが、タイトルをつけるのが難しい。逆に言えば、タイトルがついてしまえば中身を書くのは比較的簡単なのです。

技術ブログは大きく３つに分類されます。それぞれのケースで使いやすいタイトルのアイデアを書いておきました。

検索結果を見たときにタイトルだけで中身が想像できるように、固有名詞（製品名、サービス名、技術名、機能名、イベント名などなど）を盛り込むとよいでしょう。

次は中身

タイトルが決まったら、あとは中身です。

私なりの「読みやすくて役立つ技術ブログ」の共通点と、心がけていることが４つあります。

  1. １つの記事には１つの物事や結論になるようにスコープを小さくする（＝タイトルと一対一になるように）
  2. 記事の冒頭で「何を目的にして、何を行ったか」を書く
  3. １つの記事の中の小見出しを少なくする
  4. 全体的に文字数を少なくする

全般的に言えることは 簡潔であればあるほど読みやすい という事になるでしょう。

ここまで書いてて気が付きましたが、実はこの考え方は 良いコードを書く方法 と考え方は同じですね。コードも技術ブログもコンパクトなのが美しいです。

短い技術ブログの例

Ubuntu 20.04 に rbenv で Ruby 環境を整える最小手順という記事を例に見てみましょう。

ご覧の通り、目次は「前提」「インストールとアップデート方法(=作業手順)」と最後に自分がこのブログを書くのに役立ったリンクを置いてあります。

rbenvをインストールする際に「rbenv 最小手順」で探すことができれば、「未来の自分へのドキュメント」として十分に役立っていると言えるでしょう。

未来の自分が「rbenv 最小手順」で探している

長くなったらどうするか

プログラムコードと同様に分割しましょう。ネタがもう一つ増えてラッキーですね！

具体的な分割例ですが、「トラヒック計測ツール pmacct を使ってみる」 という記事があります。これは元々「低トラヒック用途向け新料金体系 「Low Data Volume」の購入方法＆使いどころ」の記事からの分割をしました。

理由は、料金の紹介なのに pmacct というツールの紹介を盛り込むのは、１つの記事で２つの物事になってしまうからです。

技術ブログの流れ＆テンプレ

こんな流れで書くのはどうでしょうか。もちろん全部書く必要はありません。

  • トライ系 (参考: トラヒック計測ツール pmacct を使ってみる )

    • 何を目的に、何をしたのか。(達成できてない場合は「できてません」も冒頭で)
    • 結論やわかったこと。(要するに、ってやつですね)
    • 実際に行った事
      • 準備（例えば OS のバージョンとか、買ったものとか。これ、結構重要です）
      • 実際にやったこと
    • 結論やわかったことに対する補足

  • 紹介系 (参考: LTEモデム搭載済みプロトタイプ向けデバイスの販売を開始しました！)

    • 製品やサービスが開発された背景
    • 製品の紹介
      • 製品やサービスの特徴や、使う事でのメリット（スペックは極力書かない）
      • 使い始めるまでの手順
      • どこで買えるの？
      • マニュアルへのリンクや、関連サービスの紹介

  • レポート系 (参考: 伊那市 LoRaWAN ハッカソン レポート)

    • 参加の目的
    • 「自分なりの」結論や得られた事（セミナー等の場合）
    • 当日の様子
      • 自分が行った事
      • 発表者と「自分なりの」要約
    • 参加の感想とふりかえり（目的が達成できたか等）
    • レポート系の場合は写真が重要 撮って撮って撮りまくれ

技術ブログを掲載する場所

技術ブログはどこで書いて公開できるのか？という件について調べてみました。

  • Qiita
    • やはり安定の Qiita でしょうか。たまーに書きたい、と言う時には便利です。個人的には「会社的にはサポートがちょっと難しいけど、技術的には可能だよ！」というネタを書くようにしています。
    • 私のアカウント: https://qiita.com/ma2shita
  • はてなブログ
    • こちらも定番。結構頻繁に書く人におすすめです。いわゆる「セルフブランディング」にも役立ちそう。
  • Zenn
  • Blogger
    • 技術ブログの老舗ですね。 Google がやってます。
  • Medium
    • 海外勢。最近技術ブログの URL に出てくるようになった気がします。

あとは WordPress 等のブログエンジンを活用して、自分で立ち上げるといった事も多くみられます。

掲載する場所についての注意

ありがちなのが「サイト立ち上げ燃え尽き症候群」と「カスタマイズ燃え尽き症候群」です。
WordPress でサイトを立ち上げた！自分好みのデザインにカスタマイズした！そこで満足してしまい、コンテンツを書く気力までたどり着かないということがあります。（私もそうでした）

そのため、なるべくサイトは立ち上げない（サービスを利用する）、あるもので満足する、そんなことを心掛けていただき、中身を作るほうに気力を持っていってください。

画像の取り扱いは Google Drive が便利

どのブログでも課題になるのが「画像」（私調べ）
例えば ID や key といったセンシティブ情報をマスキングしたり、トリミングなどなど、、、正直面倒くさいです。

そこで活用いただきたいのが Google Drive の「Google 図形描画」です。
もちろん、このブログの画像も Google Drive で作成しています。

このようにスクリーンショットを貼りつけたうえで、必要な文字やマスキングを行うことができます。

この編集した画像を直接参照する機能が Google 図形描画にはあります。
それが「ウェブに公開」です。公開をすると、公開用の img タグ、もしくは src に使える URL が入手できますので、これをそのままブログに書くだけです。

このツールを使うメリットですが下記の通りです。

  • ブラウザだけあれば、画像編集ができます。レタッチソフトは不要です
  • 公開後に画像上での変更が発生しても、再アップロードが不要です

※注意：普段のドキュメント共有に使う「共有」機能では、このように img タグとして使うことはできませんのでご注意ください。

ブログが上達するためには？

技術ブログは「未来の自分へのドキュメント」です。上手に書くよりも、残ることが重要です。要するに「自分のため」にやってみましょう。

そして、上達するには「マネをする」「何度も練習する」この二つです。マネについては、ご紹介したテンプレを使ってみてください。実はこの記事も「紹介系」のテンプレの通り進めています。テンプレで紹介したポイントがどこにあるのか？と考えながら見てみてください。

おわりに

私が一番うれしいのは、同僚から「ググったら、おぬしのブログが出てきた。参考にさせてもらったよ」と声をかけてもらう事です。みなさんもぜひ、ブログで「役立ったなー」と思った時には、TwitterやFacebookでのシェアや「いいね」などでリアクションしてみてください。

最後に、SORACOM 関連のブログ書いたら Twitter へ #SORACOM というハッシュタグをつけてツイートしてみてください。ソラコムの社員はそれが大好物でして、 SORACOM Blog でも、 “3月の IoT 記事まとめ” といった形で紹介させていただきたいのです！

― ソラコム “MAX” 松下

エンジニアブログ