Embed Size (px)
Citation preview
技術ドキュメント改善作戦 TDI-#2
Apache 設定ファイル編（２）
アイデアクラフト 開米瑞浩 http://ideacraft.jp提供
概要・想定読者
技術解説系の文書を、その技術の構造がわかるように
概念整理・図解するサンプルです。
出題・ヒントを含めているので、「技術文書をわかり
やすく書く」トレーニングに最適です。
設定マニュアルや技術解説書などを書く方。
複雑な構造を持つ情報の図解トレーニングをしたい方。
【著作権者】ドキュメント・コンサルタント 開米瑞浩
著者公式サイト http://ideacraft.jp
（最終ページに著者紹介を記載）
【本書の概要】
【想定読者】
2
本書の例題は、技術評論社より刊行の「<文章嫌いではすまされない! > エンジニアのための伝わる書き方講座」に収録されています。http://www.amazon.co.jp/dp/477416576X/
本書は、Apache設定ファイル編（１）の続編です。【注意事項】
使い方3
次のページに出題ファイルのリンクを掲載しています。ダウンロードしてください。
出題ファイルのダウンロード
本書を読み進める
気になったことは質問を！
問いかけへの答えを考えながら読んでください。１～２分で答えが見えてこなければ次へ進みましょう。
本書の答えが唯一の正解ではありません。「こういう考え方もできないか？」・・・など、気になったことがあればぜひ質問してください。（著者への連絡先は最終ページに記載）
本書では、下記出題ファイル中の「課題テキスト」を検討します。ダウンロードしてご覧ください
技術ドキュメント改善作戦 TDI-1 Apache 設定ファイル （出題）https://dl.dropboxusercontent.com/u/4325387/TDI-1-2015-0116-Apache-1.pdf出題ファイル
資料入手先
技術ドキュメント改善作戦 TDI-#1 Apache 設定ファイル編（１）http://www.slideshare.net/kaimaimizuhiro/tdi-120150116apache1
本書の前編は下記リンク先にて公開しています。
前編の振り返り5
Apache設定ファイル編（１）では、下記のように図解しました。
→ 引き続き課題テキスト（２）を検討しましょう
Apache プログラム本体
設定ファイル位置情報
メイン設定ファイル
サブ設定ファイル
サブ設定ファイル
サブ設定ファイル
起動時に -f フラグで上書き可能
通常は httpd.conf という名前で作成
Includeディレクティブで指定。ワイルドカードで一括指定可能
メイン、サブ設定ファイルの内容を変更した時はapacheの再起動が必要
拡張モジュールごと、あるいは運用しているサイトごとに設定ファイルを分ける、などの運用ができる
コンパイル時にデフォルト値が埋め込まれる
Apacheの設定ファイル説明文例6
課題テキスト（２）の内容はこうです。どのように整理しましょうか？
→ 図解したいところですが・・・
Apacheには拡張モジュールで機能を追加することができます。拡張モ
ジュールはプログラム本体とは別ファイルとして作成し、設定ファイル中の
指示により起動時に動的にプログラム本体と結合することが可能です。この
場合、拡張モジュールごとにそのモジュール関連の設定のみを記載したサブ
設定ファイルを用意し、メイン設定ファイルから拡張モジュールとサブ設定
ファイルをペアで読み込むような運用が可能です。
↓なお、ここで読まなくていいので、30秒ぐらい眺める程度で先に進んでください
↑この例文は、https://httpd.apache.org/docs/2.2/ja/configuring.html を参考にして開米が作成しましたじっくり読みたい場合は４ページ記載の資料入手先よりダウンロードしてください
「直線型」を探す7
→ たとえば・・・
直線型＝「真っ直ぐつながる論理構造」になりそうなところを探してみます。
「問題が起こる原因を究明する」、「仕事の手順を説明する」、「機械の構造を説明する」などの場面でよく現れます
睡眠不足 居眠り運転 交通事故
仕入れ 加工 販売
例1：因果関係
例2：段取り
新横浜 品川 東京例3：物理配置 名古屋京都
出典：手軽な論理図解スライドの３類型http://www.slideshare.net/kaimaimizuhiro/ss-43725972
キーワードを拾い出して並べてみます8
→ 箇条書きにすると扱いやすくなります
Apacheには拡張モジュールで機能を追加することができます。拡張モ
ジュールはプログラム本体とは別ファイルとして作成し、設定ファイル中の
指示により起動時に動的にプログラム本体と結合することが可能です。この
場合、拡張モジュールごとにそのモジュール関連の設定のみを記載したサブ
設定ファイルを用意し、メイン設定ファイルから拡張モジュールとサブ設定
ファイルをペアで読み込むような運用が可能です。
赤字にしたキーワードのみを「真っ直ぐ並べる」としたら、どういう順番が自然でしょうか？
9
→ まずは１番について考えると？
箇条書きにして1つずつ考えます
1. 拡張モジュールはプログラム本体とは別ファイルとして作成し
2. メイン設定ファイル中の指示により起動時に動的にプログラム本体と結
合することが可能
3. 拡張モジュールごとにそのモジュール関連の設定のみを記載したサブ設
定ファイルを用意し
4. メイン設定ファイルから拡張モジュールとサブ設定ファイルをペアで読
み込む
10
→ これに２番を加筆すると？
1. 拡張モジュールはプログラム本体とは別ファイルとして作成し
2. メイン設定ファイル中の指示により起動時に動的にプログラム本体と結
合することが可能
Apache プログラム本体
拡張モジュール
↓1番を図解すると、こうですね
11
→ これに３番を加筆すると？
1. 拡張モジュールはプログラム本体とは別ファイルとして作成し
2. メイン設定ファイル中の指示により起動時に動的にプログラム本体と結
合することが可能
Apache プログラム本体
拡張モジュール
起動時に動的結合
メイン設定ファイル中の指示により
↓さらに２番を加筆するとこう
12
→ これに４番を加筆すると？
3. 拡張モジュールごとにそのモジュール関連の設定のみを記載したサブ設
定ファイルを用意し
Apache プログラム本体
拡張モジュール
起動時に動的結合
メイン設定ファイル中の指示により
サブ設定ファイル
拡張モジュールごとにそのモジュール関連の
設定のみを記載したサブ設定ファイルを用意
↓さらに３番を加筆するとこう
13
→ メイン設定ファイルを四角い箱にします
4. メイン設定ファイルから拡張モジュールとサブ設定ファイルをペアで読
み込む
Apache プログラム本体
拡張モジュール
起動時に動的結合
メイン設定ファイル中の指示により
サブ設定ファイル
拡張モジュールごとにそのモジュール関連の
設定のみを記載したサブ設定ファイルを用意
↓４番を加筆するなら、「メイン設定ファイル」を「サブ設定ファイル」と同じく四角い箱で書きたいですね
14
→ どこに変える？
4. メイン設定ファイルから拡張モジュールとサブ設定ファイルをペアで読
み込む
Apache プログラム本体
拡張モジュール
起動時に動的結合
指示
サブ設定ファイル
拡張モジュールごとにそのモジュール関連の
設定のみを記載したサブ設定ファイルを用意
メイン設定ファイル
↑こう書くこともできますが、「メイン設定ファイル」の位置は変えたほうがよさそうです
15
→ 続く
4. メイン設定ファイルから拡張モジュールとサブ設定ファイルをペアで読
み込む
Apache プログラム本体
拡張モジュール
起動時に動的結合
サブ設定ファイル
拡張モジュールごとにそのモジュール関連の
設定のみを記載したサブ設定ファイルを用意
メイン設定ファイル
↑あとはこれに「ペアで読み込む」ように見える修正をすると
16
→ 続いて前編の内容と合成
4. メイン設定ファイルから拡張モジュールとサブ設定ファイルをペアで読
み込む
Apache プログラム本体
拡張モジュール
起動時に動的結合
サブ設定ファイル
拡張モジュールごとにそのモジュール関連の
設定のみを記載したサブ設定ファイルを用意
メイン設定ファイル
↑これで、「ペアで読み込む」印象が強くなります
17
→ 続く
前編（Apache設定ファイル編（１））では、下記のように図解しました。これに前ページの結果を合成してみましょう。
Apache プログラム本体
設定ファイル位置情報
メイン設定ファイル
サブ設定ファイル
サブ設定ファイル
サブ設定ファイル
起動時に -f フラグで上書き可能
通常は httpd.conf という名前で作成
Includeディレクティブで指定。ワイルドカードで一括指定可能
メイン、サブ設定ファイルの内容を変更した時はapacheの再起動が必要
拡張モジュールごと、あるいは運用しているサイトごとに設定ファイルを分ける、などの運用ができる
コンパイル時にデフォルト値が埋め込まれる
18
→ 続く
おや、意外に変化が少ないですね
Apache プログラム本体
設定ファイル位置情報
メイン設定ファイル
サブ設定ファイル
サブ設定ファイル
サブ設定ファイル
起動時に -f フラグで上書き可能
通常は httpd.conf という名前で作成
Includeディレクティブでサブ設定ファイルを読み込める。ワイルドカードで一括指定可能
拡張モジュールごと、あるいは運用しているサイトごとに設定ファイルを分ける、などの運用ができる
コンパイル時にデフォルト値が埋め込まれる
拡張モジュール
メイン、サブ設定ファイルの内容を変更した時はapacheの再起動が必要
19
課題テキスト（２）自体は結構長々と書かれていたのですが・・・・
→ 課題テキスト（１）の図に加筆してみると
Apacheには拡張モジュールで機能を追加することができます。拡張モジュー
ルはプログラム本体とは別ファイルとして作成し、設定ファイル中の指示に
より起動時に動的にプログラム本体と結合することが可能です。この場合、
拡張モジュールごとにそのモジュール関連の設定のみを記載したサブ設定
ファイルを用意し、メイン設定ファイルから拡張モジュールとサブ設定ファ
イルをペアで読み込むような運用が可能です。
20
→ 実はこういうことはよくあります
実質、変わったのはここだけです
Apache プログラム本体
設定ファイル位置情報
メイン設定ファイル
サブ設定ファイル
サブ設定ファイル
サブ設定ファイル
起動時に -f フラグで上書き可能
通常は httpd.conf という名前で作成
Includeディレクティブでサブ設定ファイルを読み込める。ワイルドカードで一括指定可能
拡張モジュールごと、あるいは運用しているサイトごとに設定ファイルを分ける、などの運用ができる
コンパイル時にデフォルト値が埋め込まれる
拡張モジュール
メイン、サブ設定ファイルの内容を変更した時はapacheの再起動が必要
21
文章で書くと非常に長くなってしまう説明が・・・
あっけないほどワンパターンで書けてしまう
きっちり構造を整理して図解すると
・・・ということがよくあります
文章解説は無駄に長くなりがち
「文章」による説明は、実質的に同じ事を何度も書いている場合があり、見た目の文字数が
多い割りには中身がなく、それでいて全部読まなければいけないから面倒くさい、という場
合が少なくないのです。
→ ここまでの教訓を振り返ります
ふりかえり（１）22
真っ直ぐ並ぶ部分を探す
「真っ直ぐ並ぶ部分」は、基本的な構造を
見つける手がかりになることが多いので、
最初に探してみてください
参考：手軽な論理図解スライドの３類型http://www.slideshare.net/kaimaimizuhiro/ss-43725972
Apache プログラム本体
拡張モジュール
起動時に動的結合
サブ設定ファイル
メイン設定ファイル
ふりかえり（２）23
長文でも恐れる必要なし
見た目は長文でも、実質的には同じことの繰り返しで、それ
ほど中身がない場合も多いので、長文だからと言って恐れず、
敬遠せずに整理してみてください
おつかれさまでした24
複雑な情報も、適切に構造化（図解）してやれば、読者は文章だ
けでの説明よりも10倍速く理解してくれます。話が通じると仕事
が楽しくなるものです。ぜひ本書の内容を参考に、自分が扱って
いる技術文書で実践してみてください。
技術ドキュメント改善作戦 TDI-#2 Apache 設定ファイル編（２）
（完）
本書は、技術文書をわかりやすく構造化する過程を「考えながら」体験できるように、随所に
出題を含めた形で整理したものです。
このコンセプトは「技術ドキュメント改善作戦」としてシリーズ化し、他の事例も提供してい
く予定です。取り上げて欲しい事例、質問／要望、指摘事項等のご連絡は著者 アイデアクラ
フト 開米瑞浩までお寄せください。連絡先は次ページに記載しております。
【著者紹介】
→著者公式サイト http://ideacraft.jpお問合せ先： http://ideacraft.jp/cms/main-contact.html
技術屋のためのドキュメント相談所（誠ブログ）→ http://blogs.bizmakoto.jp/doc-consul/
開米 瑞浩 （カイマイ ミズヒロ）
元：IT技術者。現：ドキュメント・コンサルタント。
難解な情報を整理分析して論理構造を見抜き、「素人にも分かりやすく表現する」ことを得意とする。
技術者向けの「分かりやすく書く力」研修や、難解な技術文書のリライト業務コンサルティングを提供。
技術者向けおよび一般ビジネスパーソン向けの「書く技術、説明する技術」に関する著書多数。
25
