Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

技術ドキュメント改善作戦 TDI-#2 Apache 設定ファイル編(2)

579 views

Published on

Apache の設定ファイルの説明文を題材に、文章だけの技術マニュアルをどうわかりやすく図解するか、というテーマで、思考プロセスを1ステップずつたどって考えられるように解説しました。

Apache設定ファイル編(1) の続きですので、(1)を未見の方はそちらのほうから先にご覧ください。

Published in: Engineering
  • Be the first to comment

技術ドキュメント改善作戦 TDI-#2 Apache 設定ファイル編(2)

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

×