Recomendados
Más contenido relacionado
Destacado
Destacado (20)
Similar a 技術ドキュメント改善作戦 TDI-#1 Apache 設定ファイル（１）
Similar a 技術ドキュメント改善作戦 TDI-#1 Apache 設定ファイル（１） (20)
Más de Mizuhiro Kaimai
Más de Mizuhiro Kaimai (20)
技術ドキュメント改善作戦 TDI-#1 Apache 設定ファイル（１）
- 1. 技術ドキュメント改善作戦 TDI-#1 Apache 設定ファイル編（１） アイデアクラフト 開米瑞浩 http://ideacraft.jp提供
- 2. 概要・想定読者 技術解説系の文書を、その技術の構造がわかるように 概念整理・図解するサンプルです。 出題・ヒントを含めているので、「技術文書をわかり やすく書く」トレーニングに最適です。 設定マニュアルや技術解説書などを書く方。 複雑な構造を持つ情報の図解トレーニングをしたい方。 【著作権者】ドキュメント・コンサルタント 開米瑞浩 著者公式サイト http://ideacraft.jp （最終ページに著者紹介を記載） 【本書の概要】 【想定読者】 2 本書の例題は、技術評論社より刊行の 「<文章嫌いではすまされない! > エンジニアのための伝わる書き方講座」 に収録されています。 http://www.amazon.co.jp/dp/477416576X/
- 4. 本書では、下記出題ファイル中の「課題テキスト」を検討します。 ダウンロードしてご覧ください 技術ドキュメント改善作戦 TDI-1 Apache 設定ファイル （出題） https://dl.dropboxusercontent.com/u/4325387/TDI-1-2015-0116-Apache-1.pdf出題ファイル 資料入手先
- 5. Apacheの設定ファイル説明文例 5 オープンソースのWebServerソフトウェア、Apache の設定ファイルの使 用についての説明文例ですが、もっと分かりやすく書きたいですね。 → 図解したいところですが・・・ Apache の動作設定は設定ファイルを通して行います。設定情報は複数の設定ファイルに分散させ て書き込むことができ、拡張モジュールごとや運用しているサイトごとに設定ファイルを分ける ことができます。メインの設定ファイルの名前と場所のデフォルト値はコンパイル時に設定され ていますが、起動時にコマンドラインで -f フラグを使って上書きできます。メインの設定ファイ ルは通常、httpd.confという名前で作成します。他の設定ファイルは Include ディレクティブに よって読み込むことができます（注）。この際、ワイルドカードで多数の設定ファイルを一括し て読み込み可能です。どの種類のディレクティブもどの設定ファイルにでも書くことができます。 メイン設定ファイルの内容を変更したら、変更を反映させるためにはApacheの再起動が必要です。 （注：「ディレクティブ」とは、設定ファイル中に記入する、設定命令のことです。「Include ディレクティブ」はIncludeという種類の設定命令で、他の設定ファイルをその位置に読み込むこ とを意味します。C言語でいう#include命令のようなものです） ↓なお、ここで読まなくていいので、10秒ぐらい眺める程度で先に進んでください ↑この例文は、https://httpd.apache.org/docs/2.2/ja/configuring.html を参考にして開米が作成しました じっくり読みたい場合は前ページ記載の資料入手先よりダウンロードしてください
- 7. 箇条書きにしてみましょう（１） 7 原文の一部を引用しました。 → 答えは？ メインの設定ファイルの名前と場所のデフォルト値は コンパイル時に設定されていますが、起動時に コマンドラインで -f フラグを使って上書きできます。 これを2箇条に分解してください。 （簡単な問題です）
- 8. 足りない情報を探しましょう 8 「が、」を境に前後に分けると、こうなります → 答えは？ ① メインの設定ファイルの名前と場所のデフォルト値は コンパイル時に設定されています ② 起動時にコマンドラインで -f フラグを使って 上書きできます ただし、このままだと図解にするには情報が足りません。 文①のほうに1つ足りない情報がありますが、何でしょうか？ ヒント：あるアプリの例文と比べてみましょう 使用開始前に、画面設定タブの背景色欄に背景色 コードを設定してください
- 10. 構造化すると不明な部分が見える 10 Apache の設定ファイルの例文①を当てはめるとこうなります。 → 図解のヒント アクション パラメータ ターゲット タイミング サブジェクト 不明 不明 コンパイル時 設定する 設定ファイル名 と位置 「開発者」 Apache プログラム本体 不 明 部 分 の 推 定 「不明」部分を見つけたら、技術文書に書いて役に立つような図解のパター ンを工夫します。
- 13. 「-f フラグ」を追記 13 さらに②の文（下記）の内容を追記してみましょう → 答えは？ ② 起動時にコマンドラインで -f フラグを使って上書きできます Apache プログラム本体 設定ファイルの 名前と位置 メイン設定ファイル コンパイル時に設定
- 14. 解答例（２） 14 こうなります → さらにいくつか微調整 Apache プログラム本体 設定ファイルの 名前と位置 メイン設定ファイル コンパイル時にデフォルト値を設定 起動時に -f フラグで上書き可能
- 15. 紛らわしい用語に注意（１） 15 同じ用語が違うものを指していると誤解を招きやすいので注意 → 用語を変更すると Apache プログラム本体 設定ファイルの 名前と位置 メイン設定ファイル コンパイル時にデフォルト値を設定 起動時に -f フラグで上書き可能 この２つは同じもの この２つは違うもの したがってここは用語を 変えるほうがいい
- 16. 解答例（３） 16 初心者向けになればなるほど、微妙な用語調整が重要です → to be continued... Apache プログラム本体 設定ファイルの 名前と位置 メイン設定ファイル コンパイル時にデフォルト値が 埋め込まれる 起動時に -f フラグで上書き可能 この表現のほうが、「通常はユーザーが変更する項目ではない （コンパイル時の作業なので） 」という印象に合う
- 18. 解答例（４） 18 だいたいこんな形に書けます → 続く ① 設定情報は複数の設定ファイルに分散させて書くこと ができる ② 複数の設定ファイルを使用する場合は、メイン設定 ファイル中に Includeディレクティブで他の設定ファ イルを複数指定できる ③ 設定ファイルの変更後はApacheの再起動が必要 これを元に図を加筆します
- 19. 複数あるものは複数に見せる 19 まずはこれを考えます → つまり？ ① 設定情報は複数の設定ファイルに分散させて書くこと ができる ② 複数の設定ファイルを使用する場合は、メイン設定 ファイル中に Includeディレクティブで他の設定ファ イルを複数指定できる ③ 設定ファイルの変更後はApacheの再起動が必要 「設定ファイル」が複数あるということなので、複数に見える ように書きましょう
- 21. 違うものは分けて書く 21 ②の文を読むと、「複数の設定ファイル」には「メインとその他」という関 係があることがわかります → 続く ① 設定情報は複数の設定ファイルに分散させて書くこと ができる ② 複数の設定ファイルを使用する場合は、メイン設定 ファイル中に Includeディレクティブで他の設定ファ イルを複数指定できる ③ 設定ファイルの変更後はApacheの再起動が必要 設定ファイルが「メインとその他」に分かれることを表現する ためには、複数個書く必要があります
- 23. 解答例（６） 23 こうすれば、「includeディレ クティブで指定」ということを 表現できます → 続く メイン設定ファイル 設定ファイル 設定ファイル 設定ファイル Include Include Include が、そこまで書かなくても、 これで十分でしょう メイン設定ファイル 設定ファイル 設定ファイル 設定ファイル
- 24. 図解しにくい部分は注釈で良い 24 次は③ですが・・・・ → ということで、ここまでの分をまとめて書くと・・・ ① 設定情報は複数の設定ファイルに分散させて書くこと ができる ② 複数の設定ファイルを使用する場合は、メイン設定 ファイル中に Includeディレクティブで他の設定ファ イルを複数指定できる ③ 設定ファイルの変更後はApacheの再起動が必要 これは言葉で注釈をつけておけば十分でしょう
- 25. ラフスケッチ 25 → 続く Apache プログラム本体 メイン設定ファイル 設定 ファイル 設定 ファイル 設定 ファイル 通常は httpd.conf という名前で作成 Includeディレクティブで指定する 変更した時はapacheの再起動が必要 設定ファイルの 名前と位置 コンパイル時にデフォルト値が 埋め込まれる 起動時に -f フラグで上書き可能 これで原文の内容の7割方を表現したラフスケッチ段階です。 あとは細かい調整をします。
- 28. 細かい疑問点を確認する 28 Apache プログラム本体 メイン設定ファイル サブ設定 ファイル サブ設定 ファイル サブ設定 ファイル 通常は httpd.conf という名前で作成 変更した時はapacheの再起動が必要 設定ファイルの 名前と位置 ある程度のロジックを押さえて書いた図と原文をつきあわせて見ると、 たいてい細かい疑問点、不明点が出てくるので、細部を詰めます 【疑問】サブ設定ファイルの内容を変 更したときもapacheの再起動は必要？ → そうした細部を詰めた最終形は？
- 29. 解答例（８） 29 これが最終形です。原文とつきあわせて見てみましょう Apache プログラム本体 設定ファイル位置情報 メイン設定ファイル サブ設定 ファイル サブ設定 ファイル サブ設定 ファイル 起動時に -f フラグで上書き可能 通常は httpd.conf という名前で作成 Includeディレクティブで指定。 ワイルドカードで一括指定可能 メイン、サブ設定ファイルの内容を変更した時はapacheの再起動が必要 拡張モジュールごと、あるいは運用 しているサイトごとに設定ファイル を分ける、などの運用ができる コンパイル時にデフォルト値が 埋め込まれる → ここまでの教訓を振り返ります
- 34. おつかれさまでした 34 複雑な情報も、適切に構造化（図解）してやれば、読者は文章だ けでの説明よりも10倍速く理解してくれます。話が通じると仕事 が楽しくなるものです。ぜひ本書の内容を参考に、自分が扱って いる技術文書で実践してみてください。 技術ドキュメント改善作戦 TDI-#1 Apache 設定ファイル編（１） （完） 本書は、技術文書をわかりやすく構造化する過程を「考えながら」体験できるように、随所に 出題を含めた形で整理したものです。 このコンセプトは「技術ドキュメント改善作戦」としてシリーズ化し、他の事例も提供してい く予定です。取り上げて欲しい事例、質問／要望、指摘事項等のご連絡は著者 アイデアクラ フト 開米瑞浩までお寄せください。連絡先は次ページに記載しております。
- 35. 【著者紹介】 →著者公式サイト http://ideacraft.jp お問合せ先： http://ideacraft.jp/cms/main-contact.html 技術屋のためのドキュメント相談所（誠ブログ） → http://blogs.bizmakoto.jp/doc-consul/ 開米 瑞浩 （カイマイ ミズヒロ） 元：IT技術者。現：ドキュメント・コンサルタント。 難解な情報を整理分析して論理構造を見抜き、「素人にも分かりやす く表現する」ことを得意とする。 技術者向けの「分かりやすく書く力」研修や、難解な技術文書のリラ イト業務コンサルティングを提供。 技術者向けおよび一般ビジネスパーソン向けの「書く技術、説明する 技術」に関する著書多数。 35