ブログ記事のクオリティに悩む人に読んで欲しい /「理科系の作文技術」を読み直した

2017年12月から「ブログを楽しく習慣化して書く」ことを支援するために「ブログメンタリング活動（完全無料）」をしている．既に1年以上継続していて，現在メンタリング中のメンティを含めると，計20名を超えている．「ブログを楽しく習慣化して書く」ことを支援するとは言え，メンタリング希望者は経験値によって違う課題意識を持っている．例えば「習慣化したい」というライフスタイルに課題意識を持っている人もいれば，「もっと多くの人にブログを読んで欲しい」という自己ブランディングに課題意識を持っている人もいる．その中でも特に多いのが「ブログ記事のクオリティを上げたい」という課題意識だったりする．

「ブログ記事のクオリティ」とは？

ブログ記事に「正解」はなく，誰が書いても違った良さがある．むしろ，ブロガーとしてオリジナリティを追求することも大切だと思う．さらに「ブログ記事のクオリティ」という言葉も定量的に表現しにくく，例えば PV などを指標にすることはできるけど，適切とは言えず，悩ましくもある．そこで「ブログ記事のクオリティ」を「情報を適切に伝えられること」と仮に定義するならば，「理科系の作文技術」を読むべきだと思う．現在の何倍もブログ記事のクオリティを上げることができる．

僕がはじめて「理科系の作文技術」を読んだのは，大学時代に論文（情報処理学会など）を書いていた2006年で，当時所属していた研究室の先輩に紹介してもらった．既に10年以上も経過しているけど，今でも定期的にパラパラと読んでいる．そして，今まで本書の書評記事をブログに書いていなかったことに気付き，今回改めて読み直した．よって今回は「ブロガー目線として」書評を書くことにした．

理科系の作文技術 (中公新書 (624))

目次

• 第1章 : 序章
• 第2章 : 準備作業（立案）
• 第3章 : 文章の組立て
• 第4章 : パラグラフ
• 第5章 : 文の構造と文章の流れ
• 第6章 : はっきり言い切る姿勢
• 第7章 : 事実と意見
• 第8章 : わかりやすく簡潔な表現
• 第9章 : 執筆メモ
• 第10章 : 手紙・説明書・原著論文
• 第11章 : 学会講演の要領

「理科系の人が書く仕事の文書」とは？

第1章「序章」では，そもそも「理科系の人が書く仕事の文書」として，大きく2種類の分類が紹介されている．本書の出版は1981年で，当時は「ブログ」という言葉がなかったと思うけど，個人的にはブログは「B 類」に該当すると考えている．特に「B-4」や「B-7」などはブログの特性と似ている．よって，ブロガーにとって本書が有用であると言える．

• A 類 : 自分だけが読むもの
  • A-1. メモ，手帳の類
  • A-2. 実験ノート，野帳（野外観察用の記録帳），仕事日記の類
  • A-3. 講義や講演を聞いてつくるノート，文献のぬき書き
  • A-4. カード類
  • A-5. 講義や講演をするためのノート
• B 類 : 他人に読んでもらうもの（仕事の文書）
  • B-1. 用件の手紙やメモの類
  • B-2. （所属機関内の）調査報告，出張報告，技術報告の類
  • B-3. 仕様書の類
  • B-4. 答案，レポート
  • B-5. 研究計画などの申請書
  • B-6. （学会誌などへの）原著論文，総合報告
  • B-7. その他の論説，解説，著書の類
  • B-8. 構造説明書，使用の手引

目標規定文

第2章「準備作業（立案）」では，文書を書く前に準備をする必要性が書かれている．特に重要なのが「目標規定文」で，これは「何を目標に文書を書くのか？」を事前に整理することを意味する．目標規定文を準備せずにブログ記事を書いてしまうと，書きながら軸がブレてしまう可能性がある．僕はブログ記事を書く前に，目標規定文（もしくは代替となるマインドマップ）を準備して，Trello タスクに記載するようにしている．さらに目標規定文を準備しておくと，ブログ記事の顔とも言える「タイトル」を決めるときにも役立つ．

パラグラフ

第4章「パラグラフ」では，文章の構成要素として，どのように「パラグラフ」を分割するべきか？という内容が書かれている．本書にはパラグラフの目安として「200-300字」と書いてあるけど，重要なのは「パラグラフの中で何を伝えたいのか？」であり，パラグラフを要約した文章を「トピック・センテンス」と言う．

「トピック・センテンス」を意識することにより，長くなったパラグラフに気付くことができたり，短すぎて不要なパラグラフに気付くことができる．また「トピック・センテンス」はパラグラフを要約した文章と表現することもでき，「目標規定文」と組み合わせることにより，必要最低限な文章構造を築くことができる．「パラグラフ」と「トピック・センテンス」を意識しながらブログ記事を書くと，文章が引き締まる．

ブログ記事を声に出して読む

第8章「わかりやすく簡潔な表現」は，本書の中で特に好きな章で，個人的にも1番意識している．章立ては以下となっている．

• 8.1 : 文は短く
• 8.2 : 格の正しい文を
• 8.3 : まぎれのない文を
• 8.4 : 簡潔
• 8.5 : 読みやすさへの配慮
• 8.6 : 文章の中の区切り記号
• 8.7 : 私の流儀の書き方

まず「格の正しい」とは，言葉の繋がりが適切な文章のことを言う．以下の例文（本書から引用）を見るとわかる．正しそうに見えるかもしれないけど，文末に「私は」に対応する「と思う」を追加しないと，文章として成り立たない．句読点が続く長文を書いてしまったり，主語が曖昧な文章を書いてしまうと，このように「格の正しさ」が失われる傾向が強くなると思う．

私は，この点を考えると○○氏の提出したモデルは現象を単純化しすぎている（と思う）．

次に「まぎれのない」とは，曖昧な修飾を避けた文章のことを言う．以下の例文（本書から引用）を見るとわかる．「黒い」や「きれいな」など，どこを修飾しているのかが曖昧で，読み間違えてしまう可能性がある．ある程度は文書のコンテキストによって明確になるとしても，できる限り曖昧な修飾を避けないと，読みにくくなってしまう．

黒い目のきれいな女の子がいた

第8章では，他にも以下の内容なども記載されている．個人的には漢字は積極的に使っていて，本書に書かれているような「字面の白さ」は意識していない（「普通 → ふつう」など）．

• 並記（箇条書きを活用する）
• カッコ（強調をするなど適切に使う）
• 漢字（字面を白くするために一部の漢字を平仮名にする）

本書にも書いてある通り，レビュー時に実際に文書を声に出して読むと，違和感に気付けるようになる．僕はブログ記事を公開する前に何度も読み直し，何度も声に出して読んでいる．すると，より良く書き直すことができる．

textlint-rule-preset-ja-technical-writing

「理科系の作文技術」とは直接関係はないけど，textlint を使っているなら textlint-rule-preset-ja-technical-writing を合わせて使うと，文書を読みやすく維持できる．例えば，読点の個数を制限することもできる．

github.com

まとめ

「ブログ記事のクオリティ」を「情報を適切に伝えられること」と仮に定義するならば，「理科系の作文技術」を読むべきだと思う．今回紹介した内容以外にもたくさん意識するべき内容が書かれている．そして，個人的には「ブログ記事を声に出して読む」ことをオススメする．名著を吟味しつつ，さぁ！今週もブログを書くのだ！

理科系の作文技術 (中公新書 (624))

Podcast

ブログメンタリングに関しては Podcast でも話してるので，興味があれば是非！

fukabori.fm

WIP プルリクエストの誤った merge を避ける GitHub Apps「WIP」と GitHub 新機能「Draft pull requests」

チーム開発をしていると，プルリクエストを WIP (Work In Progress) として送る場面は多くある．例えば，コードを書く前に設計相談をしたり，レビュー依頼をする前にパッケージ構成など全体感を相談したり，プロトタイプなどを一時的に公開することもある．進捗状況を可視化できたり，根本的な手戻りを減らせるメリットもある．

WIP を制御するツール 3選

WIP を積極的に使うとしても，WIP のまま誤ってプルリクエストを merge してしまう可能性もあり，WIP を制御するツールを使うことが多いと思う．僕自身が使っている（使ってきた）WIP 制御ツールを紹介しようと思う．今後は最後に紹介する GitHub 新機能「Draft pull requests」を積極的に使っていこうと思う．

• Chrome 拡張「Do Not Merge WIP for GitHub」
• GitHub Apps「WIP」
• GitHub 新機能「Draft pull requests」

Chrome 拡張「Do Not Merge WIP for GitHub」

以前は Chrome 拡張「Do Not Merge WIP for GitHub」を使っていた．プルリクエストのタイトルに "WIP" と入っていると「Merge pull request」ボタンを押せないように制御してくれる．比較的長く使っていたけど，自分自身が誤って merge をしないように制御できるだけで，チーム開発の場合はメンバー全員に Chrome 拡張をインストールしてもらう必要があった．

chrome.google.com

GitHub Apps「WIP」

去年頃からは GitHub Apps として公開されている「WIP」を使っている．プルリクエストのタイトルに "WIP" など以下のキーワードが含まれている場合，Checks に該当して「Merge pull request」ボタンを押せないように制御してくれる．

• wip
• work in progress
• 🚧

github.com

サンプルリポジトリに「WIP」を導入して，タイトルに "WIP" と含まれているプルリクエストを用意した．以下のようになる．

さらに「WIP」では GitHub Marketplace で Pro 契約をすると .github/wip.yml を使って細かく設定を書くことができる．以下のように書くと，対象をタイトル以外に広げることもできるし，独自のキーワードを設定することもできる．

locations:
- title
- label_name
- commit_subject
terms:
- do not merge
- ⛔

github.com

GitHub 新機能「Draft pull requests」

すると今月，GitHub に新機能「Draft pull requests」が追加された．プルリクエストを「ドラフト版」として送ることができる機能で，今までのように明示的に WIP と書く必要がなくなった．本当に必要だった機能と言える．

github.blog

サンプルリポジトリで試したところ，プルリクエストのステータスが「Draft」になった．「Merge pull request」ボタンを押せないように制御してくれる．さらに「ドラフト版」を通常のプルリクエストに昇格する場合は「Ready for review」ボタンを押す．ただし，一度押すと戻すことはできなさそうだった．既存のプルリクエストもあるし，もしかしたら「ドラフト版として送り忘れる」こともありそうなので，GitHub Apps「WIP」と併用しつつ，今後は公式機能を積極的に使っていこうと思う．

まとめ

• WIP を制御するツール 3選
  • Chrome 拡張「Do Not Merge WIP for GitHub」
  • GitHub Apps「WIP」
  • GitHub 新機能「Draft pull requests」
• 今後は GitHub 新機能「Draft pull requests」を積極的に使っていこうと思う
  • 既存のプルリクエストを「ドラフト版」に戻すことができないため，GitHub Apps「WIP」と併用すると良さそう

自分自身の情報収集スタイルを定期的に見直そう /「ソフトウェアエンジニアの情報収集について」を読んだ

@nikuyoshi に献本を頂き，去年「技術書典4」と「技術書典5」で頒布された「ソフトウェアエンジニアの情報収集について（改訂版）」を読んだ．本書は約50ページと薄く，すぐに読むことができる．重要なのは本書を読み終えることではなく「自分自身の情報収集スタイルを定期的に見直すこと」だと思っていて，むしろ読み終えてからがスタートと言える．厳選されたサイトの紹介以外に，情報収集のテクニックも紹介されている．

nikuyoshi.booth.pm

目次

• はじめに
  • 本書における情報収集の分類について
  • この本で説明する内容
  • この本で説明しない内容
  • 意見と質問
• 依頼事項を満たすための情報収集について
  • 検索の効率化
  • よい質問の仕方
  • 0から技術を学ぶ時に行っていること
• 日々の情報収集について
  • 社外の技術者と交流する
  • Podcast
  • メール
  • Twitter
  • 日常会話
• 役に立つ豆知識
  • 原因調査で使えるコマンド、ツールなど
  • 実践例題集

情報収集の分類

本書は「情報収集」を以下の2種類に分類している．本書に書いてある通り，シチュエーションによって情報収集のスタイルは異なり，うまく言語化されていると感じた．

• 依頼事項を満たすための情報収集
• 日々の情報収集

本書にも「依頼事項を満たすための情報収集」の中に「書籍から学ぶ」とある通り，僕自身も技術書を積極的に読んでいる．個人的に電子書籍は得意ではなく，物理本を読むことが多く，読みながら付箋を貼るスタイルをずっと貫いている．付箋は「自分だけの検索インデックス」と言い換えることもできて「依頼事項を満たす」ときに便利なリファレンス本は常に机の上に置いてある．具体的には「実践ハイパフォーマンス MySQL」や「Web API: The Good Parts」など．

実践ハイパフォーマンスMySQL 第3版

Web API: The Good Parts

質問をする / 技術者と交流をする

本書では「情報収集」の中に「質問をする」や「技術者と交流をする」など，ソフトスキルに分類されるスタイルも紹介されていて素晴らしかった．個人的には「質問をする」よりも「雑談をする」という表現を使うことが多く，コミュニケーションを通じて「質問 → 回答」という定型的な情報以外にも「少し関連する情報」も得られる可能性がある．積極的に質問（雑談）をするべきだし，組織的にも質問（雑談）を常にできるような文化を根付かせて置く必要がある．最近モブプログラミングが流行っている背景も関連していると思う．さらに質問（雑談）をすると「オートクライン」と引き起こすことができるのもメリットと言える．詳しくは以下の記事にまとめてある．あと質問をする目安として「Google : The 15 Minute Rule」が挙げられていた．

kakakakakku.hatenablog.com

The Five Orders of Ignorance

本書を読んで「無知にはレベルがある」ことを発表した論文「The Five Orders of Ignorance」があることを知った．具体的には「0 OI / 1 OI / 2 OI / 3 OI / 4 OI / 5 OI」となり，計5レベルある．プログラミング講師をしていたときに「プログラミング初心者に検索して！と言っても検索キーワードすら考えることができず，もっと具体的にサポートすると学習効率が高まる」という経験があり，まさに論文と同じ状況と言える．知れて良かった！

https://dl.acm.org/citation.cfm?id=352194dl.acm.org

アウトプットも「情報収集」と言えるのでは？

本書は「情報収集」をテーマにしているため，主に「インプット」にフォーカスした内容になっている．個人的に補足をするならば「アウトプット」も情報収集に繋がると思う．アウトプットをする過程でインプットを整理することもできるし，さらにアウトプットを読んだ人からフィードバックを頂くことで，もう1度学び直すことができる．さらにアウトプットを必要としている人は他人だけではなく「過去の自分」や「未来の自分」だったりもする．うまく学習サイクルを回すためには「インプットとアウトプットのバランス」が重要だと思う．

まとめ

• 「ソフトウェアエンジニアの情報収集について（改訂版）」を読んだ
  • 献本あざます！
• 単なる情報収集スタイルの紹介ではなく「質問をする」などソフトスキルに分類されるスタイルも紹介されていた
• 個人的には「アウトプット」も情報収集に繋がると思う

nikuyoshi.booth.pm

関連記事

著者 @nikuyoshi の記事！

nikuyoshi.hatenablog.com

よりアカデミックに「学び」を知るなら「エンジニアの知的生産術」を読むと良さそう．

kakakakakku.hatenablog.com

htmllint で Inline Configurations を使って Lint ルールをカスタマイズする

最近も HTML を書く機会が多く，HTML を実装するときには「htmllint」と CircleCI を組み合わせて Lint を実行している．「htmllint」の紹介記事は前に書いてある．

kakakakakku.hatenablog.com

the i tag is banned

Font Awesome を使って <i class="far fa-smile-wink"></i> のように絵文字を HTML に追加したら，エラーになった．「htmllint」の Lint ルールの中に tag-bans がある．今回は Font Awesome を使いたく，i タグを tag-bans から除外する必要があった．

the i tag is banned

i タグ以外だと，b タグと style タグも同じ Lint ルールでエラーになる．

the b tag is banned
the style tag is banned

理由としては htmllint init コマンドで生成されるデフォルトの .htmllintrc だと，以下のように i タグは禁止されている．

{
    （中略）
    "tag-bans": [
        "style",
        "b",
        "i"
    ],
    （中略）
}

よって .htmllintrc を修正すれば，エラーを無くすことができる．

{
    （中略）
    "tag-bans": [
        "style",
        "b"
    ],
    （中略）
}

Inline Configurations

.htmllintrc 以外に Lint ルールをカスタマイズする方法があるのかを調べるために Wiki を読んだところ，.htmllintrc に設定をする「Global Options」だけでなく，HTML に直接アノテーションを書く「Inline Configurations」もサポートされていた．

• Home · htmllint/htmllint Wiki · GitHub
• Inline Configurations · htmllint/htmllint Wiki · GitHub

「Inline Configurations」を使うと，HTML ごとに設定を変更できるため柔軟性がある．具体的には以下のように HTML のコメント形式でアノテーションを書くことで i タグのエラーを無くすことができる．

<!DOCTYPE html>
<!-- htmllint tag-bans="['style','b']" -->
<html>
  <head>

もし tag-bans の Lint ルールを全て無効化する場合は，以下のようにアノテーションを書くこともできる．

<!DOCTYPE html>
<!-- htmllint tag-bans="false" -->
<html>
  <head>

まとめ

• 「htmllint」で Lint ルールをカスタマイズする方法は「Global Options」と「Inline Configurations」がある
• HTML に直接アノテーションを書く「Inline Configurations」を使うと，HTML ごとに設定を変更できるため柔軟性がある

JetBrains プロダクトを管理するプロダクト「JetBrains Toolbox App」

「JetBrains IntelliJ IDEA」や「JetBrains RubyMine」など，JetBrains プロダクトを使って開発をしている人は多いと思うけど，個人的にオススメな「JetBrains Toolbox App」の話をすると，あまり知られていなく，まだまだ普及していなさそうに感じる．「JetBrains Toolbox App」とは，簡単に言うと「JetBrains プロダクトを管理するプロダクト」と表現することができ，無料で使うことができる．今回は普及のためにも「JetBrains Toolbox App」の便利さを紹介したいと思う．

www.jetbrains.com

アップデート / インストール

Toolbox App を使うと「インストール済の JetBrains プロダクトを最新版にアップロード」することができる．今までプロダクトごとに最新版にアップロードしていた人にとっては非常に効率良く使えるようになる．個人的には RubyMine と GoLand と PyCharm Community を使っていて，以下のキャプチャから PyCharm Community を最新版にアップデートできることがわかる．さらに Toolbox App では，新しくプロダクトをインストールをすることもできるため，JetBrains のウェブサイトにアクセスする必要もなくなる．

複数バージョン対応

Toolbox App を使うと，例えば The Early Access Program (EAP) など「複数バージョンの JetBrains プロダクトをインストール」することもできる．個人的には RubyMine (EAP) を使うことがある．

プロジェクト管理

多くの GitHub リポジトリを並行して開発する場合など，プロジェクトが多い場合に「Toolbox App から簡単にプロジェクトにアクセス」することもできる．JetBrains プロダクトを最初に起動するのではなく，Toolbox App からプロジェクトを検索できるのは非常に便利で，実際に使えばすぐに感じてもらえると思う．以下のキャプチャは載せられるようにサンプルプロジェクトを開いた状態にしてある．

詳細設定

JetBrains プロダクトごとの Settings 画面では「自動更新設定」や「Maximum Heap Size 設定」などもできる．JetBrains プロダクトを使っているとメモリ不足になる場合があり，Maximum Heap Size を増やす Tips を知っている人も多いと思う．Toolbox App から直接 Maximum Heap Size を設定できるのは地味に便利だったりする．

まとめ

JetBrains プロダクトを使っているなら「JetBrains Toolbox App」も合わせて使おう！もっと普及すると良いな！