📝

記事を書くときの自分ルール

2022/12/15に公開

アウトプット

idea

この記事はアウトプットはいいぞカレンダー 2022 の 15 日の記事です。

はじめに

記事を書くのは結構好きで、Qiita や Zenn にごそごそと書き続けてたら計 100 記事をとっくに超えてました。今知りました。
「はえ〜そんなにあったのか」って気持ちです。

ちなみに 7 年ほど前の初投稿は、「こういうときはこうすると楽だぞ」ってドヤ顔でコード書いたやつで、数行しか書いてないくせにバグってました。
公開後に即コメント通知が来て、恐る恐る見たら何人かバグ指摘をしてくれてました、懐かしい。
「いんたーねっとこわい、けどやさしい」って思った思い出の記事です。

それから時は経ちある程度は書き慣れて、ここ数年はそれなりに一貫した自分ルールみたいなものができてきています。
気にすることが定まっていると書くとき楽なので、ちょっと整理して晒してみたいと思います。

ネタにしつつあわよくば自分ルールの棚卸しもやってしまおうという魂胆です。

淡々とお送りします、興味のある箇所だけでもご覧ください。

あと、この記事のテキストは全部意味は適当です。深い意味はありません。

見た目に関して気を付けていること

英字の前後は隙間を開ける

❌ コードはGitHubにあります

✅ コードは GitHub にあります

🤔 なんか読みやすいから ( 明確な出典や根拠はない )

システムに直接影響する単語だけハイライトする

❌ PHP では、文字の出力に echo を使います
❌ PHP では、文字の出力に echo を使います

✅ PHP では、文字の出力に echo を使います

🤔 ただの英単語とシステムの動きに関係する単語を明確にわけるため

可能な限り正式な単語表記にする

❌ Type Script
❌ Node

✅ TypeScript
✅ Node.js

🤔 地味に記事の信頼感というか筆者の説得力に直結する気がするから ( 根拠なし )

適切にリストを使う

❌ 強引に文章だけでまとめる必要はない

Vim には「慣れると速い」や「設定が柔軟」や「サーバ作業時にも使える」といったメリットがあります。

✅ 必要に応じて箇条書きを使う

VIm のメリットは以下の通りです。

慣れると速い
設定が柔軟
サーバ作業時にも使える

🤔 列挙するならリストの方が伝わりやすいと思うから

かっこに頼りすぎない

❌ 強調のために安易に「」を使わない

「過度なジェネリクス」や「コールバックの多用」は「やってやったぜ」と感じますが〜

✅ 「」は発言や独白に限定する

過度なジェネリクスやコールバックの多用は「やってやったぜ」と感じますが〜

太字に頼りすぎない

❌ 太字にしないと主張が目立たないような文章にしない

macOS の場合ははじめから Ruby が使えるため インストールは不要 なので、エディタを開いて次のコードをタイプしてください。

✅ 主張文はコンパクトにする

macOS の場合は Ruby のインストールは不要です。
エディタを開いて次のコードをタイプしてください。

🤔 太字で誤魔化したくなったら、文がいまいちなことが多い ( 経験談 )

要点は emoji とかで目立たせる

この記事でも多用しています。

✅ セクションの締めなどに必要に応じて emoji を配置する

🤔 emoji に迷ったり要約することがないセクションは、主張が怪しいことが多い ( 経験談 )

日本語に関して気を付けていること

口語を使わない

❌ いろんな課題がありますが〜
❌ やっぱり大変そうです

✅ いろいろな課題がありますが〜
✅ やはり大変そうです

ただし発言や独白の「」内では許可

✅ 「やっぱりいろんな課題があって大変そうだな」と思うときは〜

🤔 統一感があると、読みやすさや雰囲気的な質が向上する気がするから ( 根拠なし )

読点を多用しない

、 のことです。

❌ 一文が全然着地しない

飲み会の焼き鳥なんですけど、ネギマやレバーやつくねといったらタレなのですが、ハツは塩もいいですけど、結局串盛りはタレにしておくのが無難です。

✅ 主張を抽出して文の構造を再考する

飲み会の焼き鳥はタレにします。
ハツは塩もいいですが、串盛りにはネギマやレバーやつくねなどがあるのでタレが無難でしょう。

🤔 文が着地しないと主張がはっきりしないから ( 個人的には読む気もなくなりやすい )

漢字をひらく

漢字をあえてひらがなで書くことをひらくといいます。

❌ 納品出来ます
❌ そんな時は時間が必要です
❌ 漢字を敢えて平仮名で書く事を開くと言います

✅ 納品できます
✅ そんなときは時間が必要です
✅ 漢字をあえてひらがなで書くことをひらくといいます

🤔 漢字が続くと読みづらいから
🤔 名詞に注目しやすくなるから

内容に関して気を付けていること

前提を整理する

❌ いきなり主張を述べる

Docker そのままは辛いので、Docker Compose を使います。

✅ 前提を整理する ( 補足する )

Docker そのままだと起動オプションをたくさん書かなければいけないので、チームで共有するのが大変です。
Docker Compose では Yaml でオプションを管理できるので、今回は Docker Compose を使います。

✅ 前提を整理する ( 断りを入れる )

この記事では Docker の基礎知識や利用経験がある方を対象としています。

Docker そのままは辛いので、Docker Compose を使います。

🤔 書いた人と読む人のミスマッチを減らしたり早めに明確にするため
🤔 読む人が自分は対象ではないと認識し、読むのをやめられるようにするため

対象を整理する

❌ 全員に刺さるようなことを書こうとする

お酒はやっぱり日本酒ですよね。ウイスキーも好きですが。ワインもいいな。僕は飲めないけど焼酎もいいですよね。

✅ 対象は絞ったうえで明記する

ここでは日本酒のみ取り上げます。

🤔 狙う領域を絞って主張を整理するため
🤔 読む人が自分は対象ではないと認識し、読むのをやめられるようにするため
🤔 全ての人と全てを同意することは不可能だから

事実は断定する

❌ Java は今バージョン 17 が LTS だと思います

✅ Java は今バージョン 17 が LTS です

🤔 調べてわかることや誰にとっても同じことをはっきりさせるため

事実以外は断定しない

❌ Haskell は難しくないです

✅ Haskell はほかの言語にはない特徴が多いので、初めはつまずくでしょう

🤔 主観は人によって違うため

伏線や仕込みをちゃんと回収する

僕が最近多用する手法です。

以下、emoji 含めて例

Docker とは

あいうえお〜かきくけこ〜

まとめ

❌ Docker はコマンドのオプションを毎回書くのが辛い
❌ チームでオプションを共有するために手順書のメンテが必要

Docker Compose とは

さしすせそ〜たちつてと〜

まとめ

✅ Docker Compose はオプションを Yaml に書ける
✅ Yaml を GitHub で共有できる

前章の課題が解決してますね

❌ Docker はコマンドのオプションを毎回書くのが辛い
❌ チームでオプションを共有するために手順書のメンテが必要

例ここまで

🤔 読んでいる人をちゃんと着地させるため
🤔 話の筋が通っているかセルフチェックできるため

構成に関して気を付けていること

ヘッダから書く

ここ数年は Markdown の # や ## の部分から書いています。

↓ はこの記事の書き初め数分のエディタです。

ひとりぼっちブレスト ^[1] で巨大で雑な箇条書きを作り、そのあと ## などで分類しながら分けていきます。

🤔 話の筋が通っているかセルフチェックできるため
🤔 セクションを書く途中であれもこれもと話が発散しづらいため

ヘッダレベルを徹底的に整理する

ここ数年は IntelliJ で記事を書いていますが、メソッド一覧のところに Markdown の場合はヘッダ一覧がでます。

↓ はこの記事のヘッダリストです。

常にここに違和感が生じていないかを確認しながら書くようにしています。

今回のような Tips 的な記事は楽ですが、ある程度の規模になるとヘッダの繋がりや整合性の調整に一番時間を使います。

たとえば ↓ の本はコマンドや図は割とすぐ書き終わって、30 ~ 40 時間くらいずっとヘッダ構成の調整をしてました。

🤔 粒度の違うヘッダがあると、何かおかしいのがわかるから
🤔 ヘッダがスムーズに書けないときは、何かおかしいのがわかるから

個々のセクションは端的にする

性格なのかどうしても記事が長くなりがちなのですが、最近は文字数だけを気にするのはやめました。

❌ 文字数を抑える
❌ セクションを長くする

✅ ヘッダが整理できているならセクションは増えていい
✅ ただし個々のセクションは端的にする

🤔 ヘッダが整っていれば、記事が長くても必要な箇所をすぐ見つけられるから ( 未検証 )
🤔 端的なセクションなら、文字が多くても読む労力はそんなに高くないから ( 未検証 )

これらをできるだけ機械でチェックする

これらのルールを、可能な範囲で機械的にチェックしています。

↓ はオレオレリンタ ( ver.1 ) の実行例です。

これは自分ルールを初めて作ったときの画像なので警告まみれですが、今はほとんど出ません。

手に慣れてきたということだと思ってます。

思い返すと、このころは Vim で書いていたのでヘッダ一覧を可視化する Vim Plugin なども作っていました。
( IntelliJ に切り替えてからはそのプラグインは使ってないな... )

適度にチェックする

チェックの目的はあくまで書くときのセルフチェックと読むときの伝わりやすさ向上なので、厳しくしすぎず適度に崩しています。

自分ルールというよりもオレオレ校正目安といったところでしょうか。

おわりに

昔のメモを引っ張り出してきて思いつきで書き始めたので「しょぼい記事になるだろうな」と思っていたのですが、整理したら意外といっぱいあってびっくりしました。

見返すともう当然になっていることもあれば、徹底できてないこともあり、僕自身も Qiita のアドカレにエントリーして書いてみてよかったなと感じています。

「読んでみたら一部でも参考になった」という箇所があれば、さらにうれしいです。

脚注

ブレインストーミング。めっちゃ意見出すってこと。記事に採用するかは度外視。 ↩︎