Zenn
Open1

自分の記事を読んで AI が作成した自分の文体

Shunsuke SuzukiShunsuke Suzuki

suzuki-shunsuke/zenn 記事のスタイルガイド

このドキュメントは、本リポジトリの記事で観察される文体パターンと好みをまとめたものです。

文体と口調

基本スタイル

  • 口調: プロフェッショナルでありながら親しみやすい
  • 人称: 自分を指す際は「自分」を使用
  • 敬語: 一貫して「です/ます」調を使用

よく使われる導入パターン

  • ツールの直接紹介: [ツール名] というツールを開発しています。
  • 目的の説明: [ツール名] という、[目的] ツールを開発しているので紹介します。
  • 機能の発表: [バージョン] から [機能] がサポートされたので紹介します。

記事構成パターン

典型的な記事の流れ

  1. 導入 - ツール/トピックの簡潔な紹介とリンク
  2. 背景/目的 (背景/なぜ必要か) - なぜこれが存在するのか
  3. X とは ([X] とは) - 定義と説明
  4. 機能/利点 - 主要ポイント、多くは箇条書き
  5. Getting Started/使用方法 - 実践的な例
  6. 詳細/実装 - 技術的な深掘り
  7. まとめ - 必要に応じて要約

セクション見出し

  • 疑問形を好む: なぜ timeout-minutes を設定すべきなのか
  • 直接的な定義: Checksum の検証とは
  • アクション指向: timeout-minutes を一括で設定

言語の好み

技術用語

  • 英語の用語は原形のまま使用（カタカナを強制しない）
  • 英語のまま使う一般的な用語: CI/CD、Pull Request (PR)、workflow、lint/linter
  • 確立された日本語を使用: 設定ファイル、環境変数
  • 半角英数字の前後には半角スペースを入れる: 例: foo です（fooですではない）

強調と引用

  • コマンド、ファイル名、コードスニペットにはバッククォートを使用
  • 日本語の引用や強調には「」を使用
  • 重要なポイントには控えめに太字（テキスト）を使用

説明フレーズ

  • といっても - 補足説明の導入
  • そこで - 解決策の提示
  • ただし - 例外や注意事項
  • ちなみに - 補足情報
  • なお - 追加の注意事項

フォーマット規則

スペーシング

  • 日本語文中の半角英数字の前後には半角スペースを入れる
    • 正: aqua というツールを開発しています
    • 誤: aquaというツールを開発しています
    • 正: version 1.0.0 をリリースしました
    • 誤: version1.0.0をリリースしました
  • ただし、句読点の前後にはスペースを入れない
    • 正: aqua を使用します。
    • 誤: aqua を使用します 。

リスト

  • 機能と利点には箇条書きを使用
  • 各ポイントの後に簡潔な説明を含むことが多い
  • 日本語と英語の用語の混在は許容

例:

* Monorepo サポート
  * Pull Request でコードを変更した working directory に対してのみ CI が実行される

コードブロック

  • 常に言語を指定: ```bash, ```yaml, ```go
  • コマンドにはシェルプロンプトを含める: bash の場合は $
  • コマンド出力の例にはshell-sessionを使用
  • 設定を示す際はファイル名を含める: ```yaml:aqua.yaml

リンク

  • 関連テキストの直後に配置
  • GitHub リポジトリ: URL を単独の行に
  • ドキュメント: 説明的なテキストとインライン

記述パターン

利点の説明

  • パターン: [action]することで、[benefit]
  • 例: checksum を検証することで、asset が悪意のあるものに置き換えられていることを検出し、インストールを未然に防ぐことが出来ます。

問題の導入

  • よく修辞疑問を使用
  • 解決策の前にコンテキストを提供
  • 具体的な例を使用

バージョン情報

  • 常に指定: 執筆時点で最新バージョンは [version] です。
  • 関連する場合はリリース日を含める

文体の選択

文末

  • 一貫した「です/ます」形
  • 仮定や予測には「でしょう」
  • 期待には「はずです」

謙遜表現

  • 個人的には - 個人的な意見
  • 思います - 考えを表す
  • かなと思います - 柔らかい意見表明

注意喚起の言葉

  • 注意が必要です
  • 気をつける必要があります
  • ～という問題があります

よく使われるフレーズ

OSS 紹介用

  • [X] を開発しています - 開発中であることを示す
  • [X] を開発しているので紹介します - 紹介の意図を明確に
  • OSS として開発しています - OSS であることを強調

機能説明用

  • 以下のことがぱっとわかります - 一目でわかることを強調
  • 簡単にできます - 容易さを強調
  • 便利です - 有用性を示す

制限事項用

  • 対応していません - サポート外
  • 必要ありません - 不要
  • 目指していません - 意図的に対象外

ドキュメント参照

外部リンクパターン

  • 公式サイト: URL を単独の行に
  • GitHub: リポジトリへの直接リンク
  • 関連記事: 簡潔なコンテキスト + URL

相互参照

  • Zenn トピックリンクを使用: https://zenn.dev/topics/[topic]
  • 関連する場合は他の記事を参照
  • 公式ドキュメントへ頻繁にリンク

技術的正確性

コード例

  • 常に動作する実践的な例
  • 必要なコンテキスト（インストール、セットアップ）を含む
  • 役立つ場合はコマンドと出力の両方を表示

バージョンの特定

  • 常にバージョン番号に言及
  • 互換性情報を含む
  • 破壊的変更に注意

記事のメタデータ

タイトルパターン

  • ツール紹介: [Tool] で [Purpose]
  • 機能発表: [Tool] が [Feature] をサポート
  • ハウツー: [Task] する

絵文字の選択

  • 💧 aqua 関連
  • 🐧 一般的なツール
  • 💪 改善
  • コンテンツに関連し、装飾的でない

トピックス

  • 最大 5 個
  • 具体的なものと一般的なものを混ぜる
  • 一般的: oss, cli, githubactions, terraform, security

品質指標

良い実践

  • 抽象的な説明より具体的な例
  • セットアップのステップバイステップ指示
  • 詳細なドキュメントへのリンク
  • 解決策の前に明確な問題提起

避けるべきこと

  • 説明なしの過度に技術的な専門用語
  • 読者の環境についての仮定
  • バージョン情報の欠如
  • タイムラインなしの未確定な約束（今後対応予定）

まとめ

文体の特徴:

  1. 明確で直接的な技術日本語
  2. 実践的で例示駆動の説明
  3. 一貫したフォーマットと構造
  4. 日本語と英語の用語の思慮深い使用
  5. 開発者体験と実用的な利点への焦点