「Every engineer is also a writer.」という目標を掲げたGoogleのテクニカルライティングコースの概要とサマリーを記載したものになります。誰でもテクニカルライターになれるかも？と思い、まとめてみました。内容は、Google翻訳したものをカテゴリ分けし、短くまとめたものです。 おおよそ5分ほどの時間があれば、読み切れる内容となっています。
Google Technical Writingとは
技術文書の改善を目的とした、技術文書の計画および作成方法を説明した無料講座です。 明確な技術文書の書き方を教えています。
講座の対象
トレーニングを受けたことがない人、TechnicalWrintingを復習する人
学習内容
コースは２つあり、事前クラスと本クラスがあります。事前クラス（One）では基本を、本クラス（Two）では、中級レベルのテクニックを学べます。
Oneの概要
単語、文章、段落、文書の書き方のポイントをまとめた講座になっています。
1.単語（名詞と動詞の使い方）
- 用語を一貫して使用します。あいまいである代名詞は避けてください。
- 受動態より能動態を優先します。
- 強い動詞を選択してください。曖昧な動詞よりも特定の動詞を選びます。
| × | 〇 |
| 本番移行、リリース、カットオーバ | 本番移行 |
| 稟議が申請された | （誰かが）稟議を申請した |
| 証跡はフォルダにある | 証跡はフォルダに存在する |
2.文章
- 各文を1つのアイデアに集中させます。
- いくつかの長い文章をリストに変換します。
- 不要な言葉を排除します。
- 順序が重要な場合は番号付きリストを使用し、順序が重要でない場合は箇条書きを使用します。
3.段落
- 各段落に対して、1つのトピックに焦点を当てます。
- 段落の中心点を確立する優れた冒頭文を作成します。
| × | 本番移行作業は12/30に移行作業準備（ＷＦ申請と移行作業手順の確認）を行い、12/31に移行作業を実施します。作業日当日は本社に８時に出社し、サーバにサインインすることから始めます。予め特権ＩＤを借用するようにしてください。 |
| 〇 | 12/30の本番移行作業は移行作業の準備を行います。・ＷＦ申請を行う・移行作業手順の確認を行う。 |
| 12/31の本番移行作業の手順は以下の通りとします。1.8時に本社に出社する。2.特権IDを借用する。3.サーバにサインインする。 |
4.文書
- あなたの聴衆が学ぶために、必要なことを定義します。
- あなたの聴衆にドキュメントを合わせてください。
- ドキュメントの最初にドキュメントの重要なポイントを設定します。
Twoの概要
より細かい文書の構成のポイントをまとめた講座になっています。図、ソースコード、チュートリアルにも言及しています。
1.書き方全般
- あなたの聴衆が受け取る様子を考えてください。
- 優れたレビュアーを見つけます。
- スタイルガイド（定型書式）を採用します。→NoteやBloggerを使うと文書をまとめるのが非常に簡単です。
- 文書を（自分自身に向けて）大声で読み上げます。
- 下書きを書いた後は、よく文書を見直してください。
2.文書の構成
- ドキュメントの概要を説明します。または、自由形式で書いてから整理します。
- ドキュメントの範囲と前提条件を紹介します。
- タスクベースの見出しを優先します。
- 情報を段階的に開示する（状況によっては）。
3.図の構成
- 1つの図面内の情報量を制限します。
- 図を作成する前に、標題を書くことを検討してください。
- 標題に要点を説明するか、画像に視覚的な手がかりを追加することにより、画像または図の関連部分に読者の注意を向けます。
4.ソースコードの構成
- 理解しやすい簡潔なサンプルコードを作成します。
- さまざまな複雑さを示すコードサンプルを提供します。
- コードのコメントは短くしますが、簡潔さよりも明快さを優先します。
- 明白なコードについてのコメントを書かないでください。
- コード内の直感的でないものにコメントを集中させます。
× Term=60 * 60 * 24 * 7 * 2; // フリートライアルの期間は2週間（60秒×60分×24時間×7日×2週の秒数） 〇 FreeTrialTerm = 60 * 60 * 24 * 7 * 2; // 2週間（/秒）
5.チュートリアルの構成
- チュートリアルでは、例を使用して概念を強化します。
- 例だけでなく、反例も提供します。
6.より良い文書とするために
- 継続的な改訂を実践します。
- ユーザーのカテゴリごとに異なる文章を提供します。→ユーザ向けマニュアル、管理者向けマニュアルが代表的な例です。
- 読者がすでに慣れ親しんでいるものと比較および対比します。→classの概念を、車の製造に例える本が昔はよくありました。今はどうなんでしょう？
まとめ
基本的な文章の書き方については、以下に紹介した「通じる文章の技術」と同じで、いつの時代も媒体が変わっても、あまり変わらないものだなという感想です。図、ソースコード、チュートリアルの書き方については、改めてGCP(GoogleCloudPlatform)などのWebサイトで、チュートリアルをみると、なるほど、と思う反面、結構読み辛いのもあるなあと思ったのは私だけではないはず。。。
