見出し画像

会社でテクニカルブログを書くために

クリエーションライン 技術ブログ

本記事は2023.07.25に投稿したクリエーションライン Tech blogからの転載です。


はじめに


こんにちは。Cloud Solution Division ＆ Data Platform Team所属の山森です。

普段はMongoDBチームのテクニカルサポートを担当しています。今年で社会人12年目になります。

前職含め、新入社員のころからずっとインフラと運用の畑で働いており、過去にはお客様のGoogle Cloud環境の保守も担当していたことがあります。

昨今、テクニカルブログを書くことが求められているITエンジニアは多いのではないでしょうか。弊社内でもブログ執筆が推奨されています。しかし、書くことが大事という共通認識はあるものの、思ったよりも投稿件数が伸びない実態があります。

そこで、ブログ公開までにどのようなプロセスを踏んでいるか、アウトプットしてみることにします。会社でテクニカルブログを書きたいけど、何からすればいいのかわからない方たちの手引きになるかと思ったからです。

あくまで私自身が会社でテクニカルブログを書くときのプロセスであり、「絶対にこうすべき」というものではありません。参考までにお読みください。


ネタ探し

ネタがなければ何も始まりません。継続的にアウトプットしなければ死んでしまう方たちは別として（稀にそういう方たちが居ます）、普段ブログを書く習慣がないと、ネタを見つける時点で苦労するのではないかと思います。

会社でテクニカルブログを書く場合、大なり小なり以下の点に期待されているかと思います。

  1. 「このスキルを持っている会社」「この知識に詳しい会社」という社外へのアピール　うまくいば問い合わせや受注につながる

  2. 転職を検討している人へのアピール　うまくいけば魅力的な人材の採用につながる


私の場合は、

  1. お客様からの問い合わせが過去にあった

  2. 検索してもヒット件数が少ない　

という観点から優先的にブログネタにしています。具体例として以下の記事をあげます。

https://www.creationline.com/tech-blog/61890

↑の記事で取り上げたOps Managerは、MongoDBのデプロイ・モニタリング・バックアップ取得などができるマネジメントツールです。テクニカルサポートをしていて、お客様からのお問い合わせもそこそこあります。しかし、Googleで検索してもOps Managerに関するコンテンツは（2023年5月時点では）かなり少なく、バージョンも古いものばかりでした。

MongoDBをデベロッパーの観点でデータベースとして触ってみた記事はそこそこあるものの、MongoDBのレプリカセットの組み方やシャーディング、バックアップ、モニタリングといった運用面での記事は少ないことに気づきました。

そこで、Ops Managerに関するブログを書いてみようと思い、まずは手元でOps Managerを構築して実際に触ってみることにしました。

Ops ManagerはWeb UIで操作可能です。「Web UIであればとりあえずHTTPS化をやってみるか。」と思いトライしてみたところ、いたるところでつまづきました。つまづいたところを含めて構築手順をブログにまとめれば、これからOps Managerを構築する方の助けになるのではないかと思いました。

自分がインターネットにコンテンツを増やすことで、Ops Managerユーザーが少しでも楽になってほしい。と思っています。そして、MongoDB販売代理店＆日本語サポートを提供している、自社への問い合わせも増えないかな。という期待も少しだけあります。


検証する＆結果を整理する

できれば実際に手元で検証してみましょう。手元で検証してみることで記事の信憑性がグンと上がります。私の場合は、Ops Managerの記事を書きあげるまでに少なくとも3回はOps Managerのインストール作業を行いました。

最初からインストール作業の数をこなすことが目的だったわけではありません。初回でつまづいた内容をメモし、次のインストールでつまづいたか検証…を繰り返した結果、そうなったというわけです。

ブログを書くまではconfluence（普段はMongoDBチーム内でナレッジの蓄積場所として使用）に手順と検証結果をまとめていました。検証の時点でスクリーンショットを撮影しておくと、ブログ記事にも使うことができるので後々楽になります。


ブログを書く

ここまで来てやっとブログ記事を書き始めます。私の場合は、導入-本編-まとめの三部構成で書くことが多いです。この記事もそうしています。以下の点を意識しながら書いています。


導入

  • 自己紹介。所属や業務経験をざっと書く。ただし、自分の趣味や家族構成といったパーソナルな情報は基本書かない。例えば、読者は書き手である私の趣味がガンプラであり、直近ではキャリバーンのハイグレードモデルが欲しいことには全く興味がない。

  • ブログ執筆の動機。なぜ書こうと思ったか。

  • 本編に関する簡単な説明。お品書き。目次。


本編

  • 実行した手順を実施した順に書いていく。

  • 途中、スクリーンショットや図解、情報ソースがあればURLを入れる。情報ソースをしっかりと示すことで記事の信憑性が上がる。情報ソースはなるべく公式ドキュメントが良い。

  • つまづいた点があれば、回避策も併せて書くことで、読者の転ばぬ先の杖となる。


まとめ

  • 〆の挨拶。この記事はここで終わりですよ。と読者に伝えるために使う。思いつかなければ、ただ事実を述べるだけでも良い。　例「今回は●●について解説しました。」

  • 最近は何かと敬遠されがちだが、「いかがでしたか？」も、〆の挨拶にあたる。

  • 自身の感想はあってもなくてもよい。イベントレポート系なら、あった方が良いかもしれない。

  • 最後に、内容に応じて自社サービスの宣伝や問い合わせリンクを入れると、読者が顧客になるための導線になる。


ブログ記事を推敲する

初稿ができたら、自分自身で推敲していきます。推敲とは、文章を何度も練り直すことです。もっと分かりやすく言うと、読者がストレスなく読めるような文章にするべく、ブラッシュアップすることです。

私は以下の観点で推敲しています。

  • 単語の揺れがないか。

  • ソフトウェアやサービスの名称は正しいか。

間違っていても読者に意味は伝わるが、正しい名称を使う方が誠実な印象になる。販売代理店をしているならこのレベルの誤りはないほうがよい。

例：「Red Hat」と「RedHat」　「debian」と「Debian GNU/Linux」

  • 話し言葉がないか。ネットスラングはないか。

例：
〇「ということで」✖「とゆうことで」　
〇「かと思いました。」✖「かと思いましたｗ」

適度に使うことで読者の緊張をほぐしたり、書き手への親近感がわいたりすることが期待できるが、上級者テクニックなので最初は使わないほうが無難。それよりは文章全体の語感をそろえることを優先する。

  • 表現や図解が一意に定まっているか。読者が曲解せず、書き手が意図した内容で理解できるようになっているか。

  • 文章がくどくないか。1文を2文に分けても意味が伝わるなら、後者の方がすっきりして見える。

例：
「今日は朝から納豆ご飯を2杯食べ、昼までおなかがいっぱいだったので、昼は食べませんでした。」

「今日は朝から納豆ご飯を2杯食べました。おなかがいっぱいだったので、昼は食べませんでした。」


  • 文章に出てくる単語と図解内の単語で相違がないか。

  • 略語を用いていないか。初めて登場する単語は、面倒でもフルで表記する。

　例：
✖「TLSが」
〇「Transport Layer Security（以下、TLS）が」


テクニカルレビューを依頼する

セキュリティ的な観点でまずいことなのに推奨していたり、公式ドキュメントの表記とズレていたりしないかを見てもらいます。自分がレビュイー（レビューされる人）であれば、この段階で正直自信のないところを相談することもあります。
初稿時点でも十分に気を付けているつもりですが、他人の目で見てもらうことで、より記事の練度があがります。

執筆ツールはGoogleドキュメントを使うようにしています。インターネットがつながっていればどこでも書けますし、提案モードを使えば修正内容のビフォーアフターが分かりやすいのでおすすめです。

提案モードに関しては以下のリンクも参考にしてくださいね。

https://support.google.com/docs/answer/6033474?hl=ja&co=GENIE.Platform%3DDesktop


投稿する

自分の場合は、投稿時間や日程はマーケティングチームにお任せしています。

会社として大きく打ち出したいリリースやニュースと被らないように、投稿時間を調整して予約してもらっています。

まとめ

今回はテクニカルブログを書くときのプロセスと、気を付けている点についてまとめてみました。

御託を並べてしまいましたが、私はもともと国語が得意な人間ではありません。国語の点数も悪かったですし、読書感想文も本当に嫌いでした。

高専時代の研究発表のために「スティーブ・ジョブズ-驚異のプレゼン」を読んだことがきっかけで、伝わりやすい文章やプレゼンについて意識するようになりました。

セカンド・インパクトは、社会人になってから「わかばちゃんと学ぶ Webサイト制作の基本〈HTML5・CSS3〉」を読んだ時です。その読みやすさに感動し、著者の湊川あいさんが書くうえで参考にしたと仰っていた「数学文章作法シリーズ」「分かりやすい表現の技術」を読みました。

仕事でもプライベートでもドキュメントやスライドを沢山作ってきましたが、まだまだ改良の余地があると思っています。文章だけでなく、イラストやマンガを組み合わせた表現を模索する毎日です。

サイボウズやクラスメソッドをはじめとしたIT大手では、テクニカルライティングの基礎や文章の組み立て方について、若手のうちから受講可能な講座やブログを書くオンボーディングがあるそうです。それだけITエンジニアにとって、テクニカルライティングが必須スキルだと考えられているということでしょう。

今回の記事が、同じようにテクニカルブログの執筆に悩む方の参考になれば幸いです。

AUTHOR

Kayou Yamamori

MongoDB日本語サポート担当。ITインフラや運用・監視・保守が好きです。
無駄のない構成やアーキテクチャを見てうっとりしています。


この記事が気に入ったらサポートをしてみませんか？