1

モウフカブール
大澤文孝

2

大澤文孝
テクニカルライター／システムエンジニア／プログラマ／インフラエンジニア。
著書はもうすぐ100冊。100冊記念パーティーやりたい（けど反対されている）。

3

主な著書

もうすぐ100冊パーティーやりたい！

雑誌記事

毎月18日
発売

人事や先輩を取材

技術者を取材

昔は、DOS/Vマガジン、インターネットマガジン、ソフマップワールドとかでも記事書いていました。

共著・お手伝いのお仕事
基の原稿にハンズオンを組み込んで再構成

基の原稿の加筆・再構成

構成確認・Python
プログラムチェック

全体構成、説明不足部分の補足、その他、編集補
佐人の原稿を読むのは勉強になる

企業内でのドキュメント・仕様書
仕様書
顧客向け説明資料
操作説明書
開発者は忙しいから、僕が代わってドキュメント書きするよ！

書き方は、それぞれ違う書籍、雑誌、仕様書、マニュアルなど、それぞれに適した書き方がある。
種類

ポイント

書籍分量がある。その人は、その分野に興味がある

雑誌分量少ない。その分野に興味があるかわからない。結論大事。いかにコンパクトにできるか。さわりが伝わればOK

仕様書

正確性が重要マニュアル

その通りにできることが大事。戸惑うところは必ず補足

スタイルに合わせるの大事！
でも気をつける基本は同じ。

アジェンダわかりやすく・読みやすくするには
1. 構成・企画
2. 丁寧に3. スタイル・ルールに従う
経験や編集さんから教わったことをもとに3つのポイントを説明

1. 構成・企画

• 構成・企画とは
1. 何を書くか（テーマ）
2. 誰向けに書くか
3. 何を扱うか（どれを落とすか）
4. どんな順序で書くか
5. 目的（読者が読んだあと、読者にどうなって欲しいか）

× 書きたいことを書く○ 伝えたいことを書く

読者はおまえを知りたいんじゃない！
おまえが書いたことを知りたい！

• 構成・企画とは
1. 何を書くか（テーマ）
2. 誰向けに書くか
3. 何を扱うか（どれを落とすか）
4. どんな順序で書くか
5. 目的（読者が読んだあと、読者にどうなって欲しいか）
マウス・キーボードの使い方知ってる？
プログラミング言語の文法知ってる？
数学・統計の知識は、どの程度ある？

• 構成・企画とは
1. 何を書くか（テーマ）
2. 誰向けに書くか
3. 何を扱うか（どれを落とすか）
4. どんな順序で書くか
5. 目的（読者が読んだあと、読者にどうなって欲しいか）
読者レベルの少し下からスタート。復習からはじめて、そこからスタートするとわかりやすくなる。

• 構成・企画とは
1. 何を書くか（テーマ）
2. 誰向けに書くか
3. 何を扱うか（どれを落とすか）
4. どんな順序で書くか
5. 目的（読者が読んだあと、読者にどうなって欲しいか）

前から読めば理解できるように。
後ろから説明することを前提にしない。

• 構成案・企画書を作る
企画・構成をまとめたものをまず作る。
→構成案・企画書
1. 何を書くか（テーマ）
2. 誰向けに書くか
3. 何を扱うか（どれを落とすか）
4. どんな順序で書くか
5. 目的（読者が読んだあと、読者にどうなって欲しいか）をまとめたもの• 構成案・企画書の例• 概要

読者対象、ゴールなども定めることが多い• 目次案

内容、流れを書く

• 見出しから決めてざっくり書く
1. （企画案からさらに掘り下げて）見出しを決める

2. ざっくり書く
3. 再調整する
・はじめからしっかり書くと書き切れない・前後関係が間違っていて、結局、労力が無駄になる・いわゆる「プロット」（設計書）を作る

構成・企画書とズレることもあるが気にしない（商業出版の場合は、同意の取り直しが必要になることもあるので編集さんと調整）。

• 雑誌の場合（先割（さきわり））
レイアウト用紙にレイアウトを決める。
見出しを決めて写真の位置を決める。本文が「何文字×何行」入るのかを決めて、それに従って、ライターは原稿を書く

文字数ぴったりに収めるのは職人技。
短い文の割に、結構、時間かかります。

• レイアウト用紙の例

編集さんがこうしたレイアウト用紙を作るよ
見開きで決めていくので、ライターと編集さんが、打ち合わせしながら、1見開きあたり、1時間ぐらいかかもこともあるよ。
結構、手間。

• 後割（あとわり）の場合「何ページ」とざっくり決められている。自由な配分で書いてもよいが……。
・アンバランスになりがち
・みっちり本文は読みにくい！ 適度に図や表があるといい・特定の見出しの本文だけ、むちゃくちゃ長いのも読みにくい。そんなときは、途中で見だしを入れて分割！
→「見出し」「こんな感じの図が入る」などは考慮すべき
とくに「図」「写真」のバランスは読みやすさで大事！
図を軽視するな（図を描くのたいへんなのはわかるけど）
書籍で「無意味なイラスト（埋め草）」が入っているのは意味がある。

• 書籍の場合
章（1章、2章）
節（1-1、1-2）
小見出し（■とか）細見出し（●とか）・特定の章や節が長い（経験的に1章が40ページ超えると、いろんな作業がきつい）・見出しの階層が細かすぎる（細見出しよりさらに小さい階層のの見出しを必要とする）
ようなときは調整を検討（商売的なことを言うと）目次に載るので、技術キーワードを入れたりするといい• 何をするのかを最初に明確に何をしているのかわからないまま手順だけ進めるのは、さっぱりわからない（内容は正しくて事実を示しているのかも知れないけれど）
手順を示すのであれば、最初に、「これから、こういうことをやっていく。そのポイントはここ」というかたちで、「何をするのか」を示そう。
できれば「解説」と「手順」は混ぜずに分離するのが理想。

ドキュメントは「事実を淡々と書くものではない」
背景の理由、解説なども大事！

• 仕様書の場合概要説明書とリファレンスは分ける。
1. 最初に概要説明を（たとえばブロック図、モジュールの連携など全体像）

2. それから詳細（たとえばリファレンス）• 書きやすいところから始める
先頭から書く必要はない。
後ろが決まらないと前が決まらないことも多い。
「第1章」とか「はじめに」は、最後に書く
最初に荒く全体を！
見直して先頭から通しでなおしていく！
最低限「2パス」は必要。よいものを作りたければ「3パス」「4パス」で。
オススメはしないが、雑誌記事では、「倍の分量を書いて、そこから削ると、質はとてもいい」
一発で書くのは絶対無理。だから、「荒くを繰り返す」で作ったほうが効率がいい。

2. 丁寧に• すっとばさない
前提を書く
・環境、揃えるものなど
・例）ネットワークやサーバだったら構成図を先に示す
これから何について伝えるかを書く

最初に読者との土台を揃える
全体像・俯瞰を示す

28

• 理論の飛躍・中間省略をしない
丁寧に説明する。中間省略しない。正確に。
例）EC2インスタンスを再起動すると、SSHで接続できなくなります。
（一見、正しそうな文章なので、タチが悪い）↓
EC2インスタンスをオン・オフすると、IPアドレスが変わるので、そのIPアドレスではSSH接続できなくなります。接続するにはIPアドレスを確認して、その新しいIPアドレスで接続し直しましょう。

• 「著者が決めたもの」か「決まりごと」かを区別する「プロジェクト名」「ファイル名」「設定名」
著者が決めたものであるなら、きちんと、「本書ではこうする」「例としてこうする」と書く。
決まりごとのファイル名、設定項目なら、「これは決まり」であることを書く
最近はフレームワークとかで、「その名前じゃないとダメ」とかあってわかりにくいのでとくに！

• それって著者の話？
決まっていることなら、可能なら原典提示（RFC-XXXXとか、仕様書のURLとか）→さらに詳しく知りたい読者が調べられる• 多くの場合そうなら「多くの場合は」• 慣例なら「慣例では」• 著者の周りなら「自分のプロジェクトでは」など
お前の企業ローカルの話を延々と書くな！

著者の周りだけの用語・略語
・プロジェクトシート（何それ？）・PR（プルリク？）・NW（ネットワーク？）「プルリクエスト（以下PR）」などと記載

お前の企業でしか通じない言葉を使うな！

3. スタイル・ルールに従う

34• スタイル・ルールとは慣例に従うことで読み手が「ぎょっとしない」• 安心感を与え、読みやすくする• 新聞・雑誌・書籍などのルールを真似る→型にはめる• 雑誌と書籍の書き方の違い「起承転結」がよいとは限らない。「結」を先頭にもってくるのがよいことも！

結論
なぜなら文章の逆三角形

日経BPの編集さんに教えてもらったよ！

新聞記事・雑誌記事は、このパターン短く伝えたいときに、とても有用補足35・ふつうの書き方
DockerはLinuxで動くコンテナ技術です。
コンテナは、それぞれ隔離されており、互いに影響を与えません。
また共通のカーネルを使うため、VMWareなどの仮想化技術に比べて軽量なのが特徴です。Dockerを使えば、たとえば1台のサーバで何十ものホスティングを実現できます。

・逆三角形で書いた場合言いたいことを先にDockerを使えば、1台のサーバで何十ものホスティングを実行できます。
なぜならDockerは互いに隔離された環境で動くコンテナを提供するからです。
共通のカーネルを使うため、VMWareなどの仮想化技術に比べて軽量という特徴もあります。

• 文言の統一
・同じことを指すのに別の言葉で言わない→読者が混乱する→あるところでは「モジュール」、あるところでは「プラグイン」など
ある程度は、編集さんがやってくれる。なので、そこまで気にしなくてOK。
だけど、技術的に細かいところをお願いするのは難しい• シンプルでわかりやすい文
・ひらがな・カタカナ、漢字の使い分け
・言い換え
・長い文の分割、入れ替えひらがな・カタカナ、漢字の使い分け「公用文における漢字使用等について」内閣訓令第1号

https://www.bunka.go.jp/kokugo_nihongo/sisaku/joho/joho/kijun/sanko/koyobun/pdf/kunrei.pdf
実体とちょっと違うひらがな・カタカナ、漢字の使い分け
共同新聞社「記者ハンドブック」
これをベースにすることが多い。
いい本だけど、「辞書」。
【基本】
・副詞は、ひらがな
・「など」「とき」「こと」などは、ひらがなひらがな・カタカナ、漢字の使い分け
ルールは絶対ではない！ あくまでも参考事項
共同新聞社「記者ハンドブック」
従うと「一般の雑誌・新聞」と近くなって、親しみがわ
これをベースにすることが多い。
いて読みやすくなるというだけいい本だけど、「辞書」。
【基本】
・副詞は、ひらがな
・「など」「とき」「こと」などは、ひらがな

ルール厨 ○ね言い換え
これも慣例。従う
必要はない

いろいろ→さまざま（「いろいろ」は口語的）することができます→できます（長くて読みにくい）
行う→別の言葉で言い換えなります→言い換えが適切のケースあり

行う
設定を行います→設定します
設定を行うことができます→設定できます「○○する」で足りるはず。

極力「行う」って言わないなります

本当になるの？ するの？

例1）この操作をすると、結果はこうなります。
→「状態が変わる」ので、これは適切な用法だと思う

例2）これまでの説明を元にプログラムを書くと、次のようになります。
→丁寧語。次のほうがよくない？

これまでの説明を元にプログラムを書いたものは、次の通りです。
好みの問題ですけど…

「なります」という表記が現れたら、「そのように状態が変化するのか？」を再確認した
い好みの問題です• 長い文と句点句点の使い方などは、この本に詳しい

駆け出しライターの頃、編集さんに教えてもらったよ読みにくいときは、前後を入れ替えて試してみるとよい例）原文
コンテナBのfuncYがコンテナCを呼び出したコンテナAのfuncXを呼び出したとき

案1）句点を入れる
コンテナBのfuncYが、コンテナCを呼び出したコンテナAのfuncXを呼び出したとき
案2）語順入れ替えて句点】
コンテナCを呼び出したコンテナAのfuncXを、コンテナBのfuncYが呼び出したとき

まとめ• 構成・企画大事
最初に書くこと、順序を決めよう。
先頭から丁寧に書くのは無駄。全体でもう一度見直すのは必然。だったら荒く全体を作っていこう• 丁寧に前提条件を飛ばさない。中間飛ばさない。自分の周りのことを一般的だと思い込まない。

• スタイル・ルールに従うテクニックの問題。すぐに実践できる！

• 文才とかは関係ないドキュメントは、「他の人のために作るもの」
読者を想像できるか手間暇かけられるか（かけなくても読者に気遣えるか）書き方を知っているか
自分で書いたものを、一歩離れて、第三者的に読むことで、よいドキュメントが書けるようになる。

今後の活動モウフカブール

小笠原種高

大澤文孝

モウフカブール
http://mofukabur.com/

同人活動「とらのあな」「メロンブックス」「Booth」「BOOK TECH」などで頒布中。

同人活動

新曲：「海とポスグレ」「僕のMaria」を収録！

メロンブックスで頒布中。
なんとか「1枚」売れました！

YouTubeチャンネル「モウフカブール」
で検索「狂気の技術音楽シリーズ_プログラマならこれを聞け」がオススメ！

https://bit.ly/OSC2021Hiroshima_Form

Follow me@sour23

https://bit.ly/OSC2021Hiroshima_Form
AWSで学ぶdocker入門書

Kindle Unlimited
で、いまなら読めます

Follow me@sour23

https://bit.ly/OSC2021Hiroshima_Form
同人誌セット

中身は、届いてからのお楽しみ！

Follow me@sour23