atman-33 Zenn技術ブログ執筆スキル
Zennの技術記事を執筆・レビューする際の基準とワークフロー。技術的正確性、読みやすさ、AIっぽい文章の排除を重視する。
記事執筆のワークフロー
- 下書き作成:
published: falseで記事を作成 - 執筆: 本スキルのルールに従って記事を執筆
- ローカルチェック:
npm run textlintでチェック - プレビュー:
npm run previewでZenn CLIプレビュー - 修正: textlintの指摘を修正
- 公開準備:
published: trueに変更 - コミット: Git commit時に自動チェックが実行される
自動チェックコマンド
npm run textlint: 全記事をチェックnpm run textlint:fix: 全記事をチェックして自動修正可能な箇所を修正
フロントマター（必須）
---
title: "記事のタイトル" # 簡潔で具体的に
emoji: "😸" # 絵文字1文字のみ
type: "tech" # tech: 技術記事 / idea: アイデア記事
topics: ["tag1", "tag2"] # 3-5個、小文字で統一
published: false # false: 下書き / true: 公開
---
topicsのルール
記号やスペースは使えない。以下のように変換する:
| 技術名 | topics表記 |
|---|---|
| C++ | cpp |
| C# | csharp |
| .NET | dotnet |
| Node.js | nodejs |
| TypeScript | typescript |
| React Native | reactnative または react-native |
文章品質の基本ルール
書くとき
- 技術用語は正確に使い、初出時に説明を追加する
- コード例は動作確認済みのものを使う
- バージョン情報は明記する（例: Node.js v20.18.1）
- 1文は60文字以内を目安に、長文は分割する
- 受動態より能動態を優先（「〜されます」→「〜します」）
- 文章の末尾は必ず「。」で終わる（「：」は禁止）
避けるべきAIっぽい表現
- 過剰な強調（「重要」「注意」の連続使用）
- 誇張表現（「革命的」「驚異的」「完璧な」）
- 情報系プレフィックス（「重要:」「注意:」「警告:」）
- コロン後のブロック（「実行します:」→「実行方法は以下の通りです。」）
- 見出し内での太字
コードブロック
- 必ず言語を指定する（
bash,javascript,typescript,python,json等） - シェルコマンドは
bashを使用 - 変数名・関数名は意味のあるものにする
- コメントは日本語で簡潔に
マークダウン
- 見出しは
#########を論理的に階層化 - リストは箇条書き（
-）を使用 - 技術用語はコードフォーマット（
`text`）で囲む - 外部リンクは参照した記事・ドキュメントに必ず貼る
- リンクテキストは具体的に（「こちら」ではなく「公式ドキュメント」）
記事本文の推奨構成
- 導入部: 問題提起や背景（2-3段落）
- 本論: 技術的説明、手順、コード例
- まとめ: 要点整理と次のステップの提示
技術ブログとしての心構え
- 読者の視点: 実際に試せる内容を提供する
- 正確性: 技術情報は必ず確認してから記載する
- 継続性: 記事は定期的に更新・メンテナンスする
詳細リファレンス
- 詳細な文章ルール、コードブロック規則、マークダウン規則: WRITING-RULES.md
- レビュー時のチェックリスト全項目: REVIEW-CHECKLIST.md