SORACOMエンジニアブログ

ソラコムの最新技術情報をお届けします

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

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

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

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

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

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

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

まずはタイトル付け

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

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

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

  • トライ系

    • ~をやってみた
    • ~をする方法
  • 紹介系

    • ~とは
    • ~はこんな時に使える
  • レポート系

    • ~に参加した
    • ~で分かった事

検索でヒットした時に、タイトルだけで中身が想像できるように、固有名詞(製品名、サービス名、技術名、機能名、イベント名などなど)を盛り込むことを忘れないようにしましょう。

次は中身

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

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

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

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

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

短い技術ブログの例

Oracleのlistener.logローテーション方法 という記事を見てみましょう。

めっちゃ短い。でも、「未来の自分へのドキュメント」としては十分ではないでしょうか。

長くなったらどうするか

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

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

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

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

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

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

    • 何を目的に、何をしたのか。(達成できてない場合は「できてません」も冒頭で)
    • 結論やわかったこと。(要するに、ってやつですね)
    • 実際に行った事
      • 準備(例えば OS のバージョンとか、買ったものとか。これ、結構重要です)
      • 実際にやったこと
    • 結論やわかったことに対する補足
  • 紹介系 (参考: LTEモデム搭載済みプロトタイプ向けデバイスの販売を開始しました!)

    • 製品やサービスが開発された背景
    • 製品の紹介
      • 製品やサービスの特徴や、使う事でのメリット(スペックは極力書かない)
      • 使い始めるまでの手順
      • どこで買えるの?
      • マニュアルへのリンクや、関連サービスの紹介
  • レポート系 (参考: 伊那市 LoRaWAN ハッカソン レポート)

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

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

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

  • Qiita
    • やはり安定の Qiita でしょうか。たまーに書きたい、と言う時には便利です。個人的には「会社的にはサポートがちょっと難しいけど、技術的には可能だよ!」というネタを書くようにしています。
  • はてなブログ
    • こちらも定番。結構頻繁に書く人におすすめです。いわゆる「セルフブランディング」にも役立ちそう。
  • Blogger
    • 技術ブログの老舗なのかな。 Google がやってます。標準ではコードハイライトが入っていませんが、カスタマイズできる ので、なんとでもなりそう。
  • Medium
    • 海外勢。最近技術ブログの URL に出てくるようになった気がします。

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

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

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

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

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

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

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

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

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

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

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

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

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

正直申し上げると、私もうまくありません。(Qiitaに書いてる記事のイイネの数を見てやってください) ただ、技術ブログは「未来の自分へのドキュメント」です。上手に書くよりも、残ることが重要です。 要するに自分のためにやってみましょう!

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

おわりに

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

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

ソラコム “MAX” 松下