writing-style

筆者の文体ルールに従って技術記事を執筆する。

記事の構成

記事は下記の順序で構成する。

1. tl;dr セクション
2. 本文（H2/H3 で構造化）
3. まとめ

tl;dr セクション

記事の冒頭に ## tl;dr を置き、箇条書きで記事の要点を列挙する。

語尾は「〜だよ」「〜するよ」「〜してね」で統一する。本文とは異なるカジュアルな口調を意図的に使う。

## tl;dr

- OpenAI が GPT-5 を発表したよ
- コーディング、数学、ライティングなどで最高性能を誇るモデルだよ
- API で使えるよ
- 実際に試してみたよ

文体

基本ルール

• 本文は「です/ます調」を基本とする
• 事実や公式情報の要約には体言止めやだ/である調を混ぜてよい
• 一つの記事の中で文体を自然に混在させる。堅すぎないトーンを保つ
• 「ですます」と「である」のどちらか一方に統一しなくてよい

体言止めの活用

事実を端的に述べるときに体言止めを使う。

Claude Code とは Terminal 上で使うことのできる Agentic なコーディングツール。

Sora 2 は動画生成における GPT-3.5 に相当する画期的なモデル。

カジュアルな表現

技術的な正確さを保ちつつ、地の文に口語的な表現を自然に混ぜる。

• 「控えめに言って面倒臭い」
• 「めちゃくちゃ便利な機能です」
• 「なんもわからんので」
• 「個人的にはオススメしません」
• 「w」や「笑」を控えめに使ってよい

推測・断定

確定的でない情報には「〜のよう。」「〜と思われます。」を使う。

個人的な意見を述べるときは「個人的には」を前置する。

確認できていない事実は正直に書く。「PR での動作報告は見当たらなかった」「手元で確認できていません」のように、未検証であることを明示する。

見出し

• H2 (##) を主要セクションの区切りに使う
• H3 (###) を H2 内のサブトピックに使う
• 見出しは短く、体言止めか名詞句にする
• 「〜とは」「〜について」「〜を試してみる」が定型

## Scoop のインストール

## 料金は?

## 使ってみた

### セットアップ

### はまりポイント

段落

• 1-3 文で 1 段落。短く切る
• 長い説明が必要な場合でも、段落を細かく分ける
• 箇条書きと地の文を交互に配置してリズムをつける

概念の説明

1. 短い定義を一文で示す
2. 公式 URL を貼る（行単独で記述し、リンクカードにする）
3. 必要なら自分の言葉で補足する

## Scoop とは

Windows 用のパッケージマネージャ（macOS でいう Homebrew）。

https://scoop.sh

「端的にいうと」「要は」で短く言い換えるのを好む。

コードブロック

• 実行コマンドと実行結果は別々のコードブロックにする
• 言語指定を付ける
• 短い説明文をコードブロックの直前に一文で置く

````markdown Scoop のバージョンを確認してみましょう。

\``bash scoop --version \``

\`` Current Scoop version: v0.5.2 - Released at 2024-07-26 \` ```

手順の書き方

• 「〜しましょう。」「〜してみましょう。」で読者と一緒に進める語り口
• 「〜してください。」で操作を指示
• 「〜してみます。」で筆者と読者が一緒に体験する感覚を出す

数値と体験

自分の体験を具体的な数値で報告する。

• 「私の場合は 30 分以内に申請が通りました。」
• 「ダウンロードに 1 時間半以上かかりました。」
• 「1 トークンの生成に 10 秒かかりました。」

外部リンク

• URL を行単独で配置し、リンクカードとして表示させる
• URL の前後に簡単な説明を添える
• 文中にインラインリンク ([text](url)) を入れない。Zenn のリンクカードプレビューを活かすため、URL は必ず独立行に置く
• ページ内アンカーリンク ([テキスト](#見出し)) は例外として OK

公式ドキュメントはこちら。

https://docs.example.com/overview

上記の公式ドキュメントより抜粋します。

読者への語りかけ

• 「あなた」とは呼ばない
• 「〜の方は」で条件分岐的に案内する
• 「みなさま」「みなさん」で全体に呼びかける
• 間違いの指摘を歓迎する: 「もし解釈違いをしていたらコメントにてご指摘くださいませ。」

Zenn 記法

• :::message で注意書きや補足情報を囲む
• :::details タイトル で折りたたみを作る
• --- 水平線をセクション間の区切りに使う

補足情報

• 翻訳文: コードブロックで囲むか blockquote で引用する

まとめセクション

記事の末尾に ## まとめ を置く。短い所感や次のアクションを書き、「以上となります。」で締める。記事全体を冗長に振り返らない。

禁止事項

• 過度に丁寧な敬語は使わない
• 冗長な前置きを書かない。すぐ本題に入る
• 読者を「あなた」と呼ばない
• 太字（text）を多用しない