Zenn
🦁

zenn で技術ブログ・エンジニアブログの運用の仕方（ポート編）

2022/10/07に公開
技術ブログ
エンジニアブログ
tech

zenn で技術ブログ・エンジニアブログの運用の仕方（ポート編）

ポートの CTO の @takuma-saito です
zenn でポートのエンジニアブログを記載することにしましたので、その背景と意図について説明します。
目的としては、社内の技術についてオープン化と中途採用の強化です。またエンジニアブログの形で社内で横断的に知見をためることによる社内のナレッジ蓄積も期待しています。
初回の記事は技術ブログを書くまでの流れを簡単にまとめています。

本当は過去にトライした技術的な施策のあれこれを記載しようと考えていましたが、技術ブログを書こうにも直近技術から離れすぎていて技術についてあまり話せることがないという残念なことに気が付き、社内で公開したエンジニアブログの運用フロー案を zenn でそのまま公開することにしました。

技術ブログを書き始めるまで

技術ブログを書きたいという要望は前々からあったものの、長続きするかどうか大きな懸念があり最初の一歩が踏み出せない状況でした。
そんな中、今年の新卒(@yanada）と 1on1 をしていたとき、「ポートでは技術ブログやらないんですか？」との要望をいただき、「本当はやりたいんだけどな〜」と思いつつ、いいきっかけなので開発部全体のチャネルで書きたい人を募集しました。
そこで想定外の 10 名前後も集まってくれたので、この際だから運用しよう！と、始めたことが直接のきっかです。

技術ブログを zenn に決めた理由

技術ブログを書くにしても媒体を決めないと先に進めません。
技術ブログを書く意思のある方を集めて、媒体として何がよいかのアンケートを取りました。
このときに候補に上がったのは Qiita と Zenn と Notion でした。
Qiita は少し初学者向きの印象がある、Notion で技術ブログはあんまり見たことがないよね、自前で用意するのは大変そう、ということで、技術的な記事をきちんとした記事を書くなら、Zenn だよねと、ほぼ満場一致で決まりました。

Zenn で記事を書く環境を整える

zenn での初期設定のあれこれ

github と連携できるそうなので、設定画面から必要なレポジトリを連携させておきます。

対象レポジトリは以下（※ 非公開レポジトリです）
https://github.com/PORT-INC/tech_blog

zenn の記事を Github で管理する場合のルール

マニュアルを見ながら基本的なことを簡単にまとみる・・

  • ディレクトリ名は articles にする
  • 拡張子は .md でマークダウン形式で記載する。articles の中に記載する記事を入れておく
  • ディレクトリ構成のサンプル
  • 記事の yaml フォーマット
    ---
title: "" # 記事のタイトル
emoji: "😸" # アイキャッチとして使われる絵文字（1文字だけ）
type: "tech" # tech: 技術記事 / idea: アイデア記事
topics: [] # タグ。["markdown", "rust", "aws"]のように指定する
published: true # 公開設定（falseにすると下書き）
published_at:  2050-06-12 09:03 # 未来の日時を指定する
---
  • published_at の日時フィールドを入れることで、記事の予約投稿をすることも可能
    • 記事公開されたら、slack の社内チャネル #web_engineer_blog に自動ポストすることもできそう？
  • 連携できるブランチは一つのみ
  • 画像を作りたい場合は images ディレクトリを作成しその中に入れて参照を貼る
  • ファイル名が slug の名前になるので、ファイル名は英文字かつ 12 文字以上がよさそう

コマンドラインツールのインストール

zenn の公式 cli が便利そう
 なので、これが利用できるような初期設定を入れておく

cli の初期設定

npm install zenn-cli

初期コマンド実行

npx zenn init

とりあえずデフォルトの記事投稿しておく

npx zenn new:article --slug hello-world-sekai --title "初めての記事投稿" --type idea --emoji "🆕" --published false

slug は 12文字以上 でないとだめらしい

published のデフォルト値は false になる。
最低限の設定として必要になるのは type と title だけ

npx zenn new:article --title "２つ目の記事投稿" --type idea

記事確認したい場合はローカルのサーバーが立ち上がる

$ npx zenn preview
👀 Preview: http://localhost:8000

メインブランチにマージ後、自動で同期される・・・

↓マージして 1 分後の記事管理画面

↓記事詳細

Github で管理している場合は管理画面で編集しても上書きされるので、アラートが出ている

Zenn の運用案

Zenn の今後のチームでの運用方法を考えました。
内容については一人で書くのはつまらないので、社内でオンラインレビューを実施しフィードバックをしながら自分も勉強したいと思います！
また、管理のしやすさから、記事は全て github で管理し、zenn の管理画面は見ないとの運用フローにします

↓以下詳細

  • 対象者は当月に翌月分の記事を書いてくる
    • published: false で記事を記載して PR を出す、ある程度ローカルの npx zenn preview を見つつ記事を修正してブランチを作る
    • PR の概要とかは書かなくても OK
  • 月の後半にエンジニアブログの共有会を実施
    • 共有会前の準備
      • 発表する資料を 2 〜 3 日前に #web_engineer_blog にポスト
    • 共有会の決めること
      • 翌々月に記事を記載する 4 名分の対象者を決める
      • 翌月分に公開する記事の順番と投稿日を決める（published_at で設定）
    • 1 人 10 分程度で記事の内容を発表 x 4 人分
      • 残り 5 分程度でそれぞれの記事に対して質問を受け付ける
      • フィードバックの内容は github の PR に転記する
  • フィードバックの修正&予約公開
    • 月末までにそれぞれフィードバックの内容を見て、適当レビューアーを 1 名設定する（持ち回り？）
      • フィードバックに完全に対応しているかどうかは見なくていい気がする
      • 誤字脱字の再チェックなど
    • 最後はレビューアーが確認してマージ

Discussion