デジタル時代の ドキュメント企画と設計


目次

はじめに
本書の読み方
 『理論編』と『実践編』の関係
 『実践編』の利用方法
     『実践編』の適用範囲
     『実践編』の説明範囲
     『実践編』の前提知識
     『実践編』に掲載しているサンプル
     『実践編』における説明の形式
     『実践編』における企画書の扱い

理論編

第1章 ドキュメント構造化とは
 1.1 ドキュメント構造化の定義
       ドキュメント構造化が求められる背景
       ドキュメント構造化
       ドキュメント構造化の目的
 1.2 ドキュメント電子標準化の定義
       ドキュメント電子標準化
       電子データ構造の標準化
       電子標準化の目的
 1.3 電子標準化のための構造化のポイント
       構造化の二面性
       本書のスタンス
       電子標準化のための構造化のポイント

第2章 構造化に関する用語の定義

       用語および説明の一覧
 2.1 モジュール
       モジュール
       情報ブロック
 2.2 階層
       階層
 2.3 アウトライン
       アウトライン
       機能別アウトライン(記載項目リスト)
       構造化アウトライン(見出しのリスト)
       詳細アウトライン(モジュール仕様)
 2.4 チュートリアルとリファレンス
       チュートリアル
       リファレンス
 2.5 レイアウト
       レイアウト
       レイアウト要素
       レイアウトの設計
 2.6 モジュール内の各要素
       リード
       小見出し
       本文
       箇条書き
       手順文
       注意・注記類(危険・警告・注意・注記など)
       参照
       グラフィック
 2.7 コントロール情報
       ノンブル
       インデックス
       ヘッダーとフッター
 2.8 スタイル
       スタイル
       スタイルの必要性
       スタイルとして登録可能なこと
       スタイルとして登録できないこと
 2.9 マスターファイル
       マスターファイル
       やむを得ずマスターファイルを変更する場合の注意

第3章 構造化の基本

       構造化の位置付け
 3.1 構造化の基本的な方式
       トップダウン方式
       ボトムアップ方式
       組み合わせ方式
 3.2 構造化作業の流れ
       構造化の方式
       記載項目のリストアップ
       モジュール化
       モジュール間の構造化
       モジュール内の構造化
       ドキュメント構成の検証
 3.3 ドキュメントの企画
       ドキュメントの作成方針
       ドキュメント運用方針
       ドキュメント体系
       ドキュメント作成基準
       ドキュメント作成作業計画
 3.4 記載項目のリストアップ
       必要と思われる項目をすべてリストアップする
       記載項目の元資料を確認する
       関連する記載項目を整理する
       ドキュメント作成の期間とコストを見積もる
 3.5 モジュール化
       情報を関連する内容ごとに切り分けてモジュール仕様を作成する
       情報の欠落や混在をなくす
       各モジュール仕様の情報量を均等にする
 3.6 モジュール間の構造化
       モジュール仕様の並び順を決める
       モジュール仕様の内容に応じて階層を付ける
       モジュール仕様の見出しを付け直してリストを作る
 3.7 モジュール内の構造化
       モジュール仕様内の情報をブロック化する
       情報ブロックの並び順を決める
       情報ブロックに適切な小見出しを付ける
 3.8 ドキュメント構成の検証
       モジュール仕様の見出しのリストを使って検証する
       ストーリーボード作業を行って検証する
 3.9 モジュール内の要素の組み立て
  3.5−1 リード
       モジュール内容の先頭にリードを入れる
       できるだけ報知的なリードにする
  3.5−2 小見出し
       小見出しには記号を付ける
       関連部分とは用語や表現を合わせる
  3.5−3 本文
       明確に論理的に記述する
       簡潔に単純に記述する
       正確かつ一義的に理解できる文にする
       適切な長さの文にする
       段落内の文の組み立てを統一する
  3.5−4 箇条書き
       箇条書きには記号を付ける
       適切な形式の箇条書きを使用する
       関連部分とは用語や表現を合わせる
       必要に応じて区切り記号を使った箇条書きを用いる
  3.5−5 手順文
       手順文には番号を付ける
       手順番号の付け方を統一する
       手順と結果を書き分ける
       操作説明の中の分岐をできる限り減らす
  3.5−6 グラフィック
       原則としてインライングラフィックにする
       キャプション(コールアウトや脚注)は図表の一部として扱う
       グラフィック用のスタイルを使用する(インライングラフィックの場合)
       必ず実寸(100%)で貼り込む
       グラフィックのサイズに応じて左右のそろえ方を変える
       図表番号と図表名を付ける
       図表番号の付け方を統一する
  3.5−7 注意・注記類(危険・警告・注意・注記など),および参照
       使用条件と記載内容を統一する
       文章やグラフィックから独立させる
       参照先をページ番号で指定しない

第4章 電子標準化のための指針
 4.1 ファイルの格納
       ファイルフォーマットを統一する
       拡張子を統一する
       ディレクトリ構成を統一する
       ファイル名の付け方を統一する
 4.2 スタイルの設定と登録
       スタイルとして登録できない書式設定をしない
       すべてのレイアウト要素のスタイルを登録する
       文章の論理構造に基づくスタイル名にする
       スタイル名を統一する
 4.3 マスターファイルの流用
       規定のマスターファイルを流用する
       マスターファイルをカスタマイズしない
 4.4 スタイルの適用
       必ずマスターファイルのスタイルを利用する
       文章の論理構造に合わせてスタイルを適用する
       すべてのレイアウト要素に対してスタイルを適用する
 4.5 文字の使用に関する指針
       英数字は半角,カタカナは全角にする
       文字罫線や外字は使用しない
       半角の「<」および「>」は使用しない
 4.6 タブとスペースの使用に関する指針
       タブで書き出し位置をそろえてはいけない
       全角スペースで書き出し位置をそろえてはいけない
       半角スペースで書き出し位置をそろえてはいけない

実践編

構造化作業の5つのステップ
各ステップのインプットとアウトプット
構造化を単品製品に適用する際の留意点

ステップ1 記載項目のリストアップ
       ステップ1の目的
       サブステップ
 1−1 必要な記載項目をリストアップする
       ポイント一覧
  ポイント1 記載項目をリストアップする基準とは
       仕様書の目次に挙がっている項目
       キーワードを含む項目
       技術者や営業担当者から要望があった項目
       前バージョンや類似製品のドキュメントに記載されてる項目
       ドキュメントの企画内容から類推できる項目
  ポイント2 記載項目をもれなくリストアップするコツ
       トップダウン方式でリストアップする
       読者の視点に立ってリストアップする
  ポイント3 元資料の情報が古い場合には
  ポイント4 元資料に矛盾がある場合には
  ポイント5 記載項目の階層や並び順を意識しないためには
  ポイント6 単品製品では細かすぎる項目をリストアップしない
 1−2 記載項目に対応する元資料を確認する
       ポイント一覧
  ポイント1 元資料の見出しとその内容が合っていない場合には
  ポイント2 情報不足の記載項目がある場合には
  ポイント3 元資料の出典と情報量の記述の仕方
  ポイント4 変更されることが事前にわかっている記載項目の扱い
  ポイント5 元資料と記載項目が1対1に対応しない場合には
 1−3 関連する記載項目を整理する
       ポイント一覧
  ポイント1 記載項目を整理する際の観点
  ポイント2 機能ごとに記載項目を整理する際のコツ
  ポイント3 操作手順ごとに記載項目を整理する際のコツ
  ポイント4 機器ごとに記載項目を整理する際のコツ
 1−4 ドキュメント作成の期間とコストを見積もる
       ポイント一覧
  ポイント1 記載項目の情報量を予想ページ数に換算する際のコツ
  ポイント2 ドキュメント全体の予想ページ数を算出する際のコツ
  ポイント3 執筆の作業期間を見積もる際の目安
  ポイント4 制作の作業期間を見積もる際の目安
       イラスト作成の作業スピード
       ページレイアウトの作業スピード

ステップ2 モジュール化
       ステップ2の目的
       サブステップ
 2−1 元資料の情報を切り分ける
       ポイント一覧
  ポイント1 モジュール仕様の台紙を作る際のコツ
  ポイント2 元資料から情報を切り抜く際のコツ
       元資料は縮小コピーしておく
       記載項目に必要な情報だけを切り抜く
  ポイント3 切り抜いた情報の管理方法
  ポイント4 内容に基づいて元資料を切り分ける際のコツ
       概論と各論に分ける
       対象読者層によって分ける
       作業段階によって分ける
       個々の機能ごとに分ける
       操作の目的ごとに分ける
       利用タイミングによって分ける
       基本と応用に分ける
       複雑さによって分ける
       使用頻度によって分ける
       利用範囲によって分ける
       重要度や緊急度によって分ける
       抽象的事項と具体的事項に分ける
  ポイント5 関連する元資料を統合する際のコツ
  ポイント6 モジュール仕様に入らない情報がある場合には
  ポイント7 単品製品では情報をまとめる(統合する)ことに重点をおく
 2−2 情報の欠落や混在をなくす
       ポイント一覧
  ポイント1 必要な情報が漏れているモジュール仕様
  ポイント2 必要な情報が漏れている場合の対処
  ポイント3 異質な情報が紛れ込んでいるモジュール仕様
  ポイント4 異質な情報が紛れ込んでいる場合の対処
 2−3 各モジュール仕様の情報量を均等にする
       ポイント一覧
  ポイント1 モジュール仕様の情報量が多すぎる場合には
       作業環境ごとに分割する
       作業段階ごとに分割する
       下位の機能ごとに分割する
       対象読者ごとに分割する
       操作手順の分岐の前後で分割する
  ポイント2 モジュール仕様の情報量が少なすぎる場合には
  ポイント3 モジュール仕様に入る情報がない場合には

ステップ3 モジュール間の構造化

       ステップ3の目的
       サブステップ
 3−1 モジュール仕様の並び順を決める
       ポイント一覧
  ポイント1 読者の視点でモジュール仕様を並べるコツ
  ポイント2 規則に沿ってモジュール仕様を並べるコツ
       概論から各論へと並べる
       作業手順に沿って並べる
       機能の構成や仕組みに合わせて並べる
       アルファベット順や50音順に並べる
       重要度や緊急度の高い事項を先に並べる
       利用頻度の高い事項を先に並べる
       基本から応用へと並べる
       簡単から複雑へと並べる
       興味が持てる順に並べる
       抽象的事項と具体的事項の順に並べる
 3−2 モジュール仕様を階層化する
       ポイント一覧
  ポイント1 階層の深さを3階層までにするコツ
       上位階層のモジュール仕様と一緒に格上げする
       上位階層で概要を示して下位階層を格上げする
       パートを作って下位階層を格上げする
       下位階層をまとめて1つのモジュール仕様にする
  ポイント2 見出しだけのモジュール仕様を作らないコツ
  ポイント3 階層内の項目を適切な数にするコツ
 3−3 モジュール仕様の見出しを付け直してリストを作る
       ポイント一覧
  ポイント1 モジュール仕様の内容を具体的に示す見出しとは
  ポイント2 具体的な見出しが付かない場合には
  ポイント3 関連する他の部分と用語や表現を合わせるコツ

ステップ4 モジュール内の構造化

       ステップ4の目的
       サブステップ
 4−1 モジュール仕様内の情報をブロック化する
       ポイント一覧
  ポイント1 説明内容の区切りごとに分ける際のコツ
       全体像と詳細事項に分ける
       操作によって分ける
       個々の機能ごとに分ける
       重要度や緊急度によって分ける
       使用頻度によって分ける
       基本と応用に分ける
       抽象的事項と具体的事項に分ける
  ポイント2 読者が一覧できる分量で分ける際のコツ
 4−2 情報ブロックの並び順を決める
       ポイント一覧
  ポイント1 読者の目的に適した順番で情報ブロックを並べるコツ
       読者が内容をスムーズに理解できるか
       読者が目的を達成することができるか
  ポイント2 規則に沿って情報ブロックを並べるコツ
       全体像から詳細事項へと並べる
       作業や操作の手順に沿って並べる
       機能の構成や仕組みに合わせて並べる
       アルファベット順や50音順に並べる
       重要度や緊急度の高い事項を先に並べる
       利用頻度の高い事項を先に並べる
       基本から応用へと並べる
       簡単から複雑へと並べる
       興味が持てる順に並べる
       抽象的事項と具体的事項の順に並べる
       問題点と解決方法の順に並べる
       結果と原因の順に並べる
 4−3 情報ブロックに適切な小見出しを付ける
       ポイント一覧
  ポイント1 適切な小見出しとは
  ポイント2 具体的な小見出しが付かない場合には
  ポイント3 関連する他の部分と用語や表現を合わせるコツ
       操作方法が似ているモジュール仕様内の説明順序を合わせる
       リファレンスではモジュール内の説明順序を合わせる

ステップ5 ドキュメント構成の検証
       ステップ5の目的
       サブステップ
 5−1 モジュール仕様の見出しのリストを使って検証する
       ポイント一覧
  ポイント1 見出しの並び順に問題はないか
  ポイント2 階層の深いところがないか
  ポイント3 見出し項目の数は適切か
  ポイント4 見出しの付け方に統一感があるか
  ポイント5 見出しから内容を類推できるか
       見出しから内容を類推する
       類似する見出しから内容を類推する
  ポイント6 本来あるべき見出し項目が抜けていないか
       チュートリアルの場合
       リファレンスの場合
 5−2 ストーリーボード作業を行って検証する
       ポイント一覧
  ポイント1 見出しと内容が合っているか
  ポイント2 モジュール仕様の並び順に問題はないか
  ポイント3 全体と部分の関係が明確になっているか
       概論モジュール
       各論モジュール
  ポイント4 技術的な間違いはないか
  ポイント5 情報ブロックの数や分量は適切か
       情報ブロックの数を検証する
       情報ブロックの分量を検証する

執筆時の留意点
       用語や表現を統一する
       文末表現を統一する
       読者の視点で記述する
       手順と結果を明確に分けて記述する
       番号は意味があるときにだけ付ける
       リード文を入れる

索引


戻る