Technical Writing ( Google Developers ) 入門
Zenn でドキュメントなどを書き始める前に Google Developers で公開されている Technical Writing コースで技術的なドキュメントの書き方をさらっと勉強してまとめます．
前提
- 翻訳記事ではありません
- 自分にとって重要だと思ったポイントだけをまとめた備忘録です
- 英語の勉強を兼ねて文章をまるごと翻訳機にかけたりはしません ( わからない単語は調べます )
Technical Writing One
Technical Writing の基礎．
Just enough grammar
英文法のおさらい．英語の品詞について書かれているだけなのでとばしてもいいかも
Words
単語の使い方について．
- 用語の「一貫性」を意識する
- 最初に使った単語の形を途中で変えると人間の頭でコンパイルエラーが起きるため理解に時間がかかる - 頭辞語は初めに定義する
- 代名詞はなるべく使わない
Active voice vs. passive voice
能動態と受動態について．
- 基本的に受動態ではなく能動態を推奨
- 受動態は結局脳内で能動態に変換されて理解されるので効率が悪い．
- Technical Writing において重要なのは「何が何に対して何をするか(したか)」を明確にすることなので能動態のほうが適している
- 学術論文は受動態が使われることが多いが Google としてはこれを変えたいきたい
→ このあたりは英語特有だなという感じ．日本語だと主語を省略することが多いのであまり意識しないかもしれない．学術論文では基本的に受動態を使うようにしてきたので少し難しい．
Clear sentence
わかりやすい sentence の書き方．
- Technical Writing で最も優先すべきことは「明快」であること
- センテンス内で最も重要なのは「動詞」
- 意味の強い動詞を使う
- There is/There are は主語が不明確なので適宜正しい主語に置き換える
- 形容詞や副詞は主観的なので Technical Writing には適さない
- 文章の可読性を高めるために1センテンスはできる限り短くする
- 1 センテンス 1 メッセージ
- 接続詞や関係代名詞で文を繋げすぎない
- 接続詞で繋げる選択肢が多い場合にはリストにする - 関係代名詞の which は補足(後ろにはなくてもいい情報が続く )
- 関係代名詞の that は拡張 ( そのアイディアを拡張するなくてはならない情報が続く )
Lists and Tables
散らばった文を整然とさせるためのリストの使い方．
- 箇条書き : 順序付けされていないもの
- 番号付きリスト : 順序に意味があるもの
- 埋め込みリスト : 文の中で繋げられたリスト
- Technical Writing では使わない方がいいので箇条書きか番号付きリストに変換する．
- リストは並列に並べる
- カテゴリやフォーマットがばらつくのはだめ
- 番号付きリストは命令形
- リストが文になっているかどうかを大文字小文字，句読点で示す
- テーブル ( 表 ) を有効に使う
- 列名にはどんなデータ入るかひと目でわかるものを入れる
- セルには長い文章/2つ以上の文章は入れない
Paragraphs
まとまりのある段落を構築するためのガイドライン．
- 段落をスタートさせる冒頭の1文が大事
- 冒頭の1文 = opening sentence にはその段落のコアとなる主張が含められる
- 1パラグラフ1トピック
- 前の段落や次の段落のトピック現在の段落で触れない (あったら無慈悲に削除するか別の段落に移す)
- 段落は短すぎても長すぎても良くない
- 1つの段落内で What, Why, How の3つの問いに答えるようにする
- What : 自分が読者に何を伝えようとしているかを明確にする
- Why : それが読者にとってなぜ重要なのかを明確にする
- How : 読者はその知識をどうやって使えばいいのかを明確にする
- また，読者はどうやってその知識が真実だと知ることができるか明確にする
Audience
良いドキュメントは対象の読者とコンテンツがマッチしているもの．
良いドキュメント = 読者がタスクを行うために必要な知識/スキル - 読者が現在持っている知識/スキル
- 対象の読者を定義する
- エンジニア，非エンジニア，科学者，理系，学生など
- それぞれ持っている知識は違う
- 知識への近さやその知識を得てからの時間経過も考慮する必要がある
- 語彙や概念は対象の読者に合わせたものを使う
- 専門家の呪い ( 自分が知っていることを相手も知っている前提で話す ) に注意する
- シンプルな単語を使う ( 英語について書かれているが日本語においても同じ )
- 特定の国の文化に依存した言い回しを使わない
- 翻訳したときに苦戦するような言い回しはよくない
Documents
センテンス，パラグラフをまとめて一つのドキュメントを作成する
- スコープの定義
- そのドキュメントがカバーする範囲を定義する
- スコープに含めないものも定義するとなおいい
- 対象となる読者の定義
- ドキュメント内で明確に定義する
- ドキュメントを理解するのに必要な知識も定義する
- あらかじめ重要なポイントを示す
- 短い要約などをつけるのも効果的
- そのドキュメンを読むのに必要となる知識をすべて説明しない
- 既存のドキュメントへのリンクなどを用いて省略する
- トピックごとにセクションを分ける
Punctuation
句読点の使い方
- 読者が文を読んだ時に自然に一時停止しそうな場所にカンマをつける
- ピリオドは異なる考えを区切るのに使う
- セミコロンは関連する２つのセンテンスをつなぐのに使う
- () は重要ではない事柄を表現する．
- 文全体を囲むときにはピリオドも中に入れる
- 文の中の一部を囲むときにはピリオドは外に出す
Markdown
マークダウンをマスターするときれいなドキュメントを書くのが楽．
Technical Writing Two
Technical Writing One を修了した人でもう少し上を目指したい人向けの中級編．
Self-editing
ドキュメントの最初のドラフトが完成したあとの修正方法
- スタイルガイドの適用
- Google developer documentation style guide
- style-guid highlight - 読者は二人称で表現する
- 条件 > 動作 の順で書く
× See [link to other document] for more information.
○ For more information, see [link to other document].
- 改めてターゲットとなる読者を意識する
- 文体を考える
- ラフにする場合がいい時もある
- 声に出して読んでみる - 時間が経ってから見返してみる
- レビューをもらう
Organaizing large docs
大量の情報をどのように整理し，まとめてドキュメントや Web にするか
- 大量の情報を整理する際のアプローチ
- 多くの情報を1つの長い文書として体系的にまとめる
- チュートリアルやリファレンスなどの玄人向けのドキュメントに適している
- 相互に関連した短い文書を複数つなげてまとめる
- 入門的な内容や初心者向けのドキュメントに適している
- 多くの情報を1つの長い文書として体系的にまとめる
- アウトラインを示す
- 情報を構造化し抽象度の高いレイヤからまとめて，段階的に詳細化していく
- ドキュメントの introduction を作る
- スコープを明確に
- ナビゲーションを追加する
- 導入，要約，リンク，つぎのステップなど
- タスクベースの見出しをつける
- 動詞ベースでタスクを切って見出しをつける
- 見出しの下に簡単な紹介文をつけ，文脈を提供する
- 新しい情報が多すぎると混乱するので必要なタイミングを見計らって提供する
Illustlating
テキスト以上にイラスト1枚の持つ情報量は多い
- イラストがあることが読者にとっては大きな助けとなる
- イラストを置く前にキャプションを考える
- キャプションは的確にイラストを説明する短い文でなくてはならない
- イラストの持つ情報は制限する
- 複雑で分かりづらい図はむしろ混乱を招く
- 長過ぎる説明はしない
- 吹き出し ( 矢印 ) で図の特定の場所へ注意を引く
- イラストもブラッシュアップする
- イラスト作成用のツールを使う ( SVG 形式がおすすめ )
Creating Sample Code
優れたサンプルコードは最高のドキュメントになる
- エラーやバグ，脆弱性が含まれないことは担保する
- サンプルコードは必ずテストする
- スニペット ( 1行程度の短いプログラム ) を使う
- サンプルコードの実行方法を示す
- 期待されるインプットとアウトプットを明確に示す
- 短く，必要な部分のみのスニペットとして記述する
-
リーダブルコードに書いてあるようなことは全部守る
- 命名
- 簡潔さ
- コメント
- サンプルコードの実行方法は明確に示す
- 副作用などが含まれないようにする
まとめ
使われている英語がとてもシンプルで理解しやすく構成やナビゲーションなど Technical Writing 自体が読みやすかったです．内容的には英語独特のものも多かったですが，論文はほとんど英語で書いているのでとても参考になる内容でした．
書いてあることはパッと見「当たり前じゃん」と思うようなことなのですが，自分のドキュメントを見返してみると意外とできていないことばかりだったので，改めて体系的に学ぶことができてとても良かったです．これで論文やドキュメントを書くスキルが少しは上がったはず．さっそく次回の書き物から実践していきたいと思います！
Discussion