• 
• 
• 
• 
• 
• Warp(type1)     Overscroll(type1)     Warp(type2)    

1.技術ドキュメント改善作戦 TDI-#1 Apache 設定ファイル編（１）
アイデアクラフト 開米瑞浩 http://ideacraft.jp提供

2.概要・想定読者・使い方
技術解説系の文書を、その技術の構造がわかるように 概念整理・図解するサンプルです。 出題・ヒントを含めているので、「技術文書をわかり やすく書く」トレーニングに最適です。
本書以外には特に必要ありません。 途中、随所にある質問への答えを考えながら読み進めてく ださい。
設定マニュアルや技術解説書などを書く方。
複雑な構造を持つ情報の図解トレーニングをしたい方。
【著作権者】ドキュメント・コンサルタント 開米瑞浩
著者公式サイト http://ideacraft.jp （最終ページに著者紹介を記載） 【使い方】
【本書の概要】 【想定読者】 2 本書の例題は、技術評論社より刊行の 「<文章嫌いではすまされない! > エンジニアのための伝わる書き方講座」 に収録されています。 http://www.amazon.co.jp/dp/477416576X/
【宣伝】

$(document).ready(function() {
  $('dl.expander dd:eq(0)').expander();

  $('dl.expander dd:gt(0)').expander({
    collapseTimer: 4000,
    beforeExpand: function() {
      $(this).parent().parent().append('<div class="success">before expand.</div>');
    },
    afterExpand: function() {
      $(this).parent().parent().append('<div class="success">after expand.</div>');
    },
    onCollapse: function(byUser) {
      var by = byUser ? 'user' : 'timer';
      $(this).parent().parent().append('<div class="success">on collapse (' + by + ').</div>');
    }
  });
});

$('ul.expander li').expander({
  slicePoint: 50,
  widow: 2,
  expandEffect: 'show',
  userCollapseText: '[^]'
});

<li>Run a marathon <span class="read-more"><a href="#">[...]</a></span><span class="details">and qualify for Boston.</span></li>

$('div.expander').expander();

オープンソースのWebServerソフトウェア、Apache の設定ファイルの使 用についての説明文例ですが、もっと分かりやすく書きたいですね。
→ 図解したいところですが・・・

Apache の動作設定は設定ファイルを通して行います。設定情報は複数の設定ファイルに分散させ て書き込むことができ、拡張モジュールごとや運用しているサイトごとに設定ファイルを分ける ことができます。

メインの設定ファイルの名前と場所のデフォルト値はコンパイル時に設定され ていますが、起動時にコマンドラインで -f フラグを使って上書きできます。
メインの設定ファイ ルは通常、httpd.confという名前で作成します。他の設定ファイルは Include ディレクティブに よって読み込むことができます（注）。この際、ワイルドカードで多数の設定ファイルを一括し て読み込み可能です。
どの種類のディレクティブもどの設定ファイルにでも書くことができます。 メイン設定ファイルの内容を変更したら、変更を反映させるためにはApacheの再起動が必要です。
（注：「ディレクティブ」とは、設定ファイル中に記入する、設定命令のことです。
「Include ディレクティブ」はIncludeという種類の設定命令で、他の設定ファイルをその位置に読み込むこ とを意味します。C言語でいう#include命令のようなものです）
↓なお、ここで読まなくていいので、10秒ぐらい眺める程度で先に進んでください
↑この例文は、https://httpd.apache.org/docs/2.2/ja/configuring.htmlを参考にして開米が作成しました

分解して攻略せよ 4
→ 具体的には・・・ 図解したいとは思っても、複雑・長文すぎるとどこから手を付けていいのか 見当もつかないのが普通です
一気に全部やろうとせずに A
分解して、出来そうな ところから攻略しましょう
C B E D F

Paragarph no. 6 箇条書きにしてみましょう（１） 5 原文の一部を引用しました。 → 答えは？ メインの設定ファイルの名前と場所のデフォルト値は コンパイル時に設定されていますが、起動時に コマンドラインで -f フラグを使って上書きできます。 これを2箇条に分解してください。 （簡単な問題です）

Paragarph no. 7 足りない情報を探しましょう 6 「が、」を境に前後に分けると、こうなります → 答えは？ ① メインの設定ファイルの名前と場所のデフォルト値は コンパイル時に設定されています ② 起動時にコマンドラインで -f フラグを使って 上書きできます ただし、このままだと図解にするには情報が足りません。 文①のほうに1つ足りない情報がありますが、何でしょうか？ ヒント：あるアプリの例文と比べてみましょう 使用開始前に、画面設定タブの背景色欄に背景色 コードを設定してください

Paragarph no. 8 「設定する」動作に関わる情報の構造 7 「設定する」という動作に関係する情報の典型的な構造はこうです → Apache設定ファイルの例文の場合は？ ユーザーが 画面設定タブの 背景色欄に アクション パラメータ ターゲット 使用開始前にタイミング サブジェクト 設定します 背景色コードを 補足：「動作」を表す概念にはこのパターンがよく出てきます。 英文法が得意なら、SVOO文型に修飾語をつけたものをイメージしてください。

Paragarph no. 9 構造化すると不明な部分が見える 8 Apache の設定ファイルの例文①を当てはめるとこうなります。 → 図解のヒント アクション パラメータ ターゲット タイミング サブジェクト 不明 不明 コンパイル時 設定する 設定ファイル名 と位置 「開発者」 Apache プログラム本体 不 明 部 分 の 推 定 「不明」部分を見つけたら、技術文書に書いて役に立つような図解のパター ンを工夫します。
Paragarph no. 10 構造イメージが湧くように図解 9 前ページの情報を元に書き直した①の文（下記）を参考に、 Ａ、Ｂ、Ｃ、Ｄに適当な情報を当てはめてみましょう → 答えは？ Ａ Ｂ Ｃ D （①修正版） メインの設定ファイルの名前と場所のデフォルト値は コンパイル時にApacheプログラム本体に設定されています
Paragarph no. 11 解答例（１）
10 文①の図解、解答例です → これに文②を追加しましょう Apache プログラム本体 設定ファイルの 名前と位置 メイン設定ファイル コンパイル時にデフォルト値を設定

Paragarph no. 12 「-f フラグ」を追記 11さらに②の文（下記）の内容を追記してみましょう → 答えは？ ② 起動時にコマンドラインで -f フラグを使って上書きできます． Apache プログラム本体設定ファイルの名前と位置メイン設定ファイルコンパイル時に設定
Paragarph no. 13 解答例（２） 12 こうなります → さらにいくつか微調整 Apache プログラム本体 設定ファイルの 名前と位置 メイン設定ファイル コンパイル時にデフォルト値を設定 起動時に -f フラグで上書き可能

Paragarph no. 14 紛らわしい用語に注意（１） 13 同じ用語が違うものを指していると誤解を招きやすいので注意 → 用語を変更すると Apache プログラム本体 設定ファイルの 名前と位置 メイン設定ファイル コンパイル時にデフォルト値を設定 起動時に -f フラグで上書き可能 この２つは同じもの この２つは違うもの したがってここは用語を 変えるほうがいい

Paragarph no. 15 解答例（３） 14 初心者向けになればなるほど、微妙な用語調整が重要です → to be continued... Apache プログラム本体 設定ファイルの 名前と位置 メイン設定ファイル コンパイル時にデフォルト値が 埋め込まれる 起動時に -f フラグで上書き可能 この表現のほうが、「通常はユーザーが変更する項目ではない （コンパイル時の作業なので） 」という印象に合う

Paragarph no. 16 箇条書きにしてみましょう（２） 15 次は原文中の下記記述に注目しましょう → 答えは？ 設定情報は複数の設定ファイルに分散させて書き込むこ とができ・・（中略）・・他の設定ファイルは Include ディレクティブによって読み込むことができます・・ （中略）・・設定ファイルを変更したら、変更を反映さ せるためにはApacheの再起動が必要です。 また箇条書きにしてみると？

Paragarph no. 17 解答例（４） 16 だいたいこんな形に書けます → 続く ① 設定情報は複数の設定ファイルに分散させて書くこと ができる ② 複数の設定ファイルを使用する場合は、メイン設定 ファイル中に Includeディレクティブで他の設定ファ イルを複数指定できる ③ 設定ファイルの変更後はApacheの再起動が必要 これを元に図を加筆します

Paragarph no. 18 複数あるものは複数に見せる 17 まずはこれを考えます → つまり？ ① 設定情報は複数の設定ファイルに分散させて書くこと ができる ② 複数の設定ファイルを使用する場合は、メイン設定 ファイル中に Includeディレクティブで他の設定ファ イルを複数指定できる ③ 設定ファイルの変更後はApacheの再起動が必要 「設定ファイル」が複数あるということなので、複数に見える ように書きましょう

Paragarph no. 19 解答例（５） 18 「複数作成可能」であることを説明する方法はこの2種類 → その理由は？ 設定ファイル 設定ファイル 設定ファイル 設定ファイル 実際に複数個書いて表現 設定ファイル （複数作成可能） 注釈で表現 今回はこちらを採用します。 なぜでしょう？

Paragarph no. 20 違うものは分けて書く 19 ②の文を読むと、「複数の設定ファイル」には「メインとその他」という関 係があることがわかります → 続く ① 設定情報は複数の設定ファイルに分散させて書くこと ができる ② 複数の設定ファイルを使用する場合は、メイン設定 ファイル中に Includeディレクティブで他の設定ファ イルを複数指定できる ③ 設定ファイルの変更後はApacheの再起動が必要 設定ファイルが「メインとその他」に分かれることを表現する ためには、複数個書く必要があります

Paragarph no. 21 関係性を表現しましょう 20 「メインとその他」に分けて表現します → 続く メイン設定ファイル 設定ファイル 設定ファイル 設定ファイル 次は、「includeディレクティブで指定」 というところを表現してみると・・・・

Paragarph no. 22 解答例（６） 21 こうすれば、「includeディレ クティブで指定」ということを 表現できます → 続く メイン設定ファイル 設定ファイル 設定ファイル 設定ファイル Include Include Include が、そこまで書かなくても、 これで十分でしょう メイン設定ファイル 設定ファイル 設定ファイル 設定ファイル

Paragarph no. 23 図解しにくい部分は注釈で良い 22 次は③ですが・・・・ → ということで、ここまでの分をまとめて書くと・・・ ① 設定情報は複数の設定ファイルに分散させて書くこと ができる ② 複数の設定ファイルを使用する場合は、メイン設定 ファイル中に Includeディレクティブで他の設定ファ イルを複数指定できる ③ 設定ファイルの変更後はApacheの再起動が必要 これは言葉で注釈をつけておけば十分でしょう

Paragarph no. 24 ラフスケッチ 23 → 続く Apache プログラム本体 メイン設定ファイル 設定 ファイル 設定 ファイル 設定 ファイル 通常は httpd.conf という名前で作成 Includeディレクティブで指定する 変更した時はapacheの再起動が必要 設定ファイルの 名前と位置 コンパイル時にデフォルト値が 埋め込まれる 起動時に -f フラグで上書き可能 これで原文の内容の7割方を表現したラフスケッチ段階です。 あとは細かい調整をします。

Paragarph no. 25 紛らわしい用語に注意（２） 24 → 具体的には？ Apache プログラム本体 メイン設定ファイル 設定 ファイル 設定 ファイル 設定 ファイル 設定ファイルの 名前と位置 ハッキリ名前を変えたほうが いいんじゃない？ こちらを「メイン」と呼応す る名前に変えればよさそう 紛らわしい名前、用語には特に注意しましょう

Paragarph no. 26 解答例（７） 25 → まだあります Apache プログラム本体 メイン設定ファイル サブ設定 ファイル サブ設定 ファイル サブ設定 ファイル 設定ファイルの 名前と位置 「メイン」と「サブ」で区別 サブの代わりに「補助」、「副」 なども有力 複数の要素の関連性がイメージしやすい名前を選びます

Paragarph no. 27 細かい疑問点を確認する 26 Apache プログラム本体 メイン設定ファイル サブ設定 ファイル サブ設定 ファイル サブ設定 ファイル 通常は httpd.conf という名前で作成 変更した時はapacheの再起動が必要 設定ファイルの 名前と位置 ある程度のロジックを押さえて書いた図と原文をつきあわせて見ると、 たいてい細かい疑問点、不明点が出てくるので、細部を詰めます 【疑問】サブ設定ファイルの内容を変 更したときもapacheの再起動は必要？ → そうした細部を詰めた最終形は？

Paragarph no. 28 解答例（８） 27 これが最終形です。原文とつきあわせて見てみましょう Apache プログラム本体 設定ファイル位置情報 メイン設定ファイル サブ設定 ファイル サブ設定 ファイル サブ設定 ファイル 起動時に -f フラグで上書き可能 通常は httpd.conf という名前で作成 Includeディレクティブで指定。 ワイルドカードで一括指定可能 メイン、サブ設定ファイルの内容を変更した時はapacheの再起動が必要 拡張モジュールごと、あるいは運用 しているサイトごとに設定ファイル を分ける、などの運用ができる コンパイル時にデフォルト値が 埋め込まれる → ここまでの教訓を振り返ります

Paragarph no. 29 ふりかえり（１） 28 長文を何度も読んで考える 箇条書きに分解してみる 長く複雑な文章を、頭の中だけで何度も読んでも、正確に理 解するのは非常に困難です。 そこで、「これは確実に読み取れる」ということを短い箇条 書きにして切り出してください。全文ではなく、目立ったと ころ、読み取りやすいところだけでかまいません

Paragarph no. 30 ふりかえり（２） 29 省略されている情報を探す 文章というのは一部の情報が省略されていても違和感なく読 めてしまうことがあります。それに気づかないと図解できま せん。 （やっかいなことに、 「美しい文章の書き方」 のセオリーの中に「当たり前すぎるこ とは書かない」「繰り返しになることは書かない」というものがあるため、省略して書 いたほうが文章としては上手なように見えます。文学作品ならそれでいいのですが、エ ンジニアリング用文書で省略表現を使うとわかりにくくなってしまいます）

Paragarph no. 31 ふりかえり（３） 30 紛らわしい用語に注意 極力、1つの言葉が1つの意味だけを表すように注意します。 ? 「設定ファイル」だけだと区別できないので「メイン」「サブ」と呼び分ける。 ? 「コンパイル時に設定されています」と「設定ファイル」の２つの「設定」が 同じアクションを意味していると誤解しやすいので、片方の用語を変更 本件では以下２つの例がありました。

Paragarph no. 32 ふりかえり（４） 31 ある程度図解してから原文を 読み直して細部を補足 図に書くと、原文で説明し切れていない細部や、矛盾がある 部分（誤読した、もしくは原文の間違い）に気がつきます。

Paragarph no. 35 おつかれさまでした 32 複雑な情報も、適切に構造化（図解）してやれば、読者は文章だ けでの説明よりも10倍速く理解してくれます。話が通じると仕事 が楽しくなるものです。ぜひ本書の内容を参考に、自分が扱って いる技術文書で実践してみてください。 技術ドキュメント改善作戦 TDI-#1 Apache 設定ファイル編（１） （完） 本書は、技術文書をわかりやすく構造化する過程を「考えながら」体験できるように、随所に 出題を含めた形で整理したものです。 このコンセプトは「技術ドキュメント改善作戦」としてシリーズ化し、他の事例も提供してい く予定です。取り上げて欲しい事例、質問／要望、指摘事項等のご連絡は著者 アイデアクラ フト 開米瑞浩までお寄せください。連絡先は次ページに記載しております。

Paragarph no. 36 【著者紹介】 →著者公式サイト http://ideacraft.jp お問合せ先： http://ideacraft.jp/cms/main-contact.html 技術屋のためのドキュメント相談所（誠ブログ） → http://blogs.bizmakoto.jp/doc-consul/ 開米 瑞浩 （カイマイ ミズヒロ） 元：IT技術者。現：ドキュメント・コンサルタント。 難解な情報を整理分析して論理構造を見抜き、「素人にも分かりやす く表現する」ことを得意とする。 技術者向けの「分かりやすく書く力」研修や、難解な技術文書のリラ イト業務コンサルティングを提供。 技術者向けおよび一般ビジネスパーソン向けの「書く技術、説明する 技術」に関する著書多数。

Paragarph no. 37 Ut non enim eleifend felis pretium feugiat. Vivamus quis mi. Phasellus a est. Phasellus magna. In hac habitasse platea dictumst. Curabitur at lacus ac velit ornare lobortis.

Paragarph no. 38 Curabitur a felis in nunc fringilla tristique. Morbi mattis ullamcorper velit. Phasellus gravida semper nisi. Nullam vel sem. Pellentesque libero tortor, tincidunt et, tincidunt eget, semper nec, quam. Sed hendrerit.

Paragarph no. 39 Morbi ac felis. Nunc egestas, augue at pellentesque laoreet, felis eros vehicula leo, at malesuada velit leo quis pede. Donec interdum, metus et hendrerit aliquet, dolor diam sagittis ligula, eget egestas libero turpis vel mi. Nunc nulla.

Paragarph no. 40 Fusce risus nisl, viverra et, tempor et, pretium in, sapien. Donec venenatis vulputate lorem. Morbi nec metus. Phasellus blandit leo ut odio. Maecenas ullamcorper, dui et placerat feugiat, eros pede varius nisi, condimentum viverra felis nunc et lorem. Sed magna