Googleのテクニカルライティングページを日本語で要約してみる（2-1）

 前回に引き続き、GoogleのTechnical Writing twoのページを日本語で要約してみます。

自己編集

• スタイルガイドを採用する
• 読者の視点で草稿を読む
• 声に出して読む
• 草稿を書いた後、時間を置いてから読み直す
• 草稿を別のドキュメントにコピーして、フォント、サイズ、色を変更する
• スタイルガイドに精通した同僚に、草稿をレビューしてもらう

大きな文書の整理

• 文書のアウトラインの作成から始める
• 各ステップは、概念の説明、または、特定のタスクの完了に限定する
• 読者にとって関連性の高い情報が紹介されるようにする
• 概念の説明と実践的な手順を交互に記述する文書は好ましい
• 書き始める前に、アウトラインを共同作業者と共有する
• 文書についての紹介文をつける
• 文書の内容
• 読者に期待する事前知識
• 文書に記載されない内容
• ナビゲーションを追加する
• 導入部と概要
• 主題の展開
• 見出し
• 目次
• 関連情報・詳細情報へのリンク
• 次に学ぶべきことへのリンク
• タスクベースの見出しが好ましい
• 各見出しの直後に見出しを配置しない
• 見出しの下には、少なくとも簡単な紹介をつける
• 段階的に情報を開示する
• 新しい用語・概念は、それが必要な指示の近くで説明するようにする
• 長々とした文章にならないよう、必要に応じて、表・図・リスト・見出しを導入する
• 1つの手順のリストが複雑で長い場合、できたら短いサブタスクに分割して再整理する
• 簡単な例と手順から始める。徐々に複雑なテクニックを追加する。

イラスト・画像

• 画像を作成する前にキャプションを書く
• 簡潔に
• 要点を説明
• 注目すべきポイントを明示
• 1つの画像内の情報量は、できるだけ少なくする
• 複雑なものは分割する
• 画像のどこに注目させたいか、手がかりを追加する
• 赤い円で囲む、吹き出しをつける、矢印で誘導する、など
• 画像・イラストも推敲する
• どうやれば簡略化できるか
• さらに単純なものに分割できないか
• 画像・イラスト内の文字は読みやすいか
• 不要な部分はないか
• SVG形式がおすすめ

サンプルコード

• 優れたサンプルコードは下記の条件を満たす
• 正しい
• 簡潔
• すぐに理解できる
• 簡単に再利用できる
• 正しいサンプルコードの基準
• エラーなくビルドする
• 実行すると説明したタスクを実行する
• できるだけ本番環境に対応する
• 言語固有の規則に従う
• サンプルコードは必ずテストする
• 保守もする
• 単体テストとサンプルプログラムは分けて考える
• サンプルコードの実行に必要な作業を指示する
• 読者が指示通りに準備するとは限らない
• 実行が難しいサンプルコードの場合、予想される出力・結果を説明しておくのもよい
• 正確さと簡潔さなら、常に正確さを優先する
• 無関係なコードを含まない
• 理解できるサンプルコードの推奨事項
• クラス名、メソッド名、変数名をわかりやすくする
• 解読しやすくする
• 深いネストを避ける
• 強調表示を乱用しない
• サンプルコード内のコメントの推奨事項
• コメントは短くする
• ただし、常に正確さを優先する
• 明白な部分についてはコメントを書かない
• 初心者にとって何が明白でないかに注意する
• コード内の直感的でない部分に注力してコメントをつける
• 読者が精通している場合は、何を実行しているかではなく、なぜ実行しているかをコメントで説明する
• 簡単に再利用可能なコードに必要なこと
• サンプルコードを実行するために必要な情報
• 依存関係やセットアップなど
• 拡張またはカスタマイズできるコード
• 何をしてはいけないか、反例も併せて示すことも有益
• 簡単な例から始め、徐々に複雑な例を載せる