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

今回要約にチャレンジするのは、GoogleのTechnical Writing Oneのページ。

Technical Writing One では、より明確な技術文書を書く方法を学びます。

単語

  • 読者が知らない・なじみのない用語は説明をつける
    • 既存の用語なら、既存の説明にリンクする
    • 独自の用語なら、定義を説明する
      • 独自の用語が多いなら、用語集にまとめる
  • 用語は文書内で一貫させる
    • 同義語で代用しない
    • 用語の短縮名を明示した上で、短縮名を使うのは問題ない
  • 頭字語（単語の頭文字をつなげた用語。例：WHO）を使うときは、略していない正式名称を最初に記載する。その際太字にする。
    • 例：World Health Organization（WHO）は、日本語では世界保健機関と呼ばれ……
    • 一つの用語は、正式名称か頭字語のどちらか一方に揃える
  • 代名詞はできるだけ使わない

能動態

  • 受動態はできるだけ避け、能動態で書く

明快な文章

  • 具体的・正確・強い動詞を使う
    • 一般的な動詞より、専門的な動詞を使う
  • 意味のある主語を使う
  • 形容詞と副詞は最小限にする

短い文章

  • 1つの文には1つの内容だけにする。
  • リストにできる部分はリストにする
  • 不要な単語は削る
  • 主旨と外れる従属節は、別の文に分ける

リストと表

  • 順序を入れ替えても意味が変わらないなら箇条書きリストを使う
  • 順序を入れ替えると意味が変わるなら番号付きリストを使う
  • リストの項目は並列（文法形式が同じ）にする
  • リストの項目が文ならば句読点をつける
  • 表は各列に、内容を表すヘッダーをつける
  • 表の各セルの内容は短くまとめる
  • 同じ列内の内容は並列にする
  • リストと表には、何を表しているかを示す文をつける

段落

  • 段落の冒頭文は、その段落のテーマを表していると効果的である
    • 場合によっては、疑問文から始めて、読者の興味を引くなどの方法も効果的である
  • 1つの段落内では、1つのトピックについてのみ書く
  • 段落は長すぎず、短すぎないようにする
    • 英語の文では、1段落につき3～5文が適当
  • 次の3つに答えられるのが優れた段落である
    • 読者に何を伝えたいか
    • 読者はなぜこれを知る必要があるか
    • 読者は内容をどう活用すべきか、または、読者は内容が正しいことをどうやって確認できるか

読者

  • 優れた文章 = 読者がタスクを実行するために必要な知識とスキル - 読者の現在の知識とスキル
  • 対象読者の役割を定義する
  • 対象読者がタスクを達成するために、何を学ぶ必要があるかを判断する
  • 語彙を対象読者に合わせる
  • 自分がすでに知っていることも、初心者は知らない、ということを意識する
  • 時代遅れの単語や複雑すぎる単語は避ける
  • 文化的な比喩・言及は使わない
  • 慣用句は使わない

文書

  • 文書が説明する範囲を定義する
    • 対象読者が、文書内で説明されることを期待するが、文書内で書かれない範囲についても、定義してあるとなお良い
  • 対象読者を明示的に指定する
    • 場合によっては、対象読者の知識や経験も指定する
  • 文書の冒頭に重要なポイントをまとめる
  • 読者のニーズを定義し、何を書くべきか判断する
    • 対象読者は誰か
    • 対象読者の目標は何か
    • 対象読者は事前に何を知っているか
    • 対象読者が文書を読んだ後、何を知るべきか、または、なにをできるようになるか


コメント

コメントを投稿

このブログの人気の投稿

令和6年度春期の応用情報技術者試験（AP）を受験しました

  応用情報技術者試験を受験してみようと思ったきっかけ 情報処理安全確保支援士試験に興味を持ったのがきっかけです。基本情報は数年前に合格しているので、応用情報技術者を飛ばして受験してみるのもアリかな～と思ったのですが（実際参考書は安全確保支援士試験のものを先に買いました）、後述の理由で受けるならやっぱり順序立てて受けようかな、と。応用情報技術者試験に合格したら、支援士試験や他の高度試験の午前1が免除される、というのもあります。 ではなぜ情報処理安全確保支援士試験に興味を持ったかというと、仕事の関係でセキュリティについて勉強する必要に駆られたからです。それで勉強を始めたのですが、知らないこと・覚えていないこと・理解できていなことがいっぱいあるな～となりました。で、教材のひとつにIPAのセキュリティ情報を使っていたのもあり、情報処理安全確保支援士試験について知り、これを機に受けてみるのもいいかな？　と参考書を1冊購入。 で、参考書を一通り読んだのですが、前提知識となる部分（ネットワークの仕組みなど）の理解がそもそも浅いな～と思い、やっぱり先に応用情報技術者を勉強しようか、とこちらも参考書を1冊購入して、一通り読みました。 去年の10月ごろに、次の春期試験受けようかな～どうしようかな～と悩んでいてブログにも一度書きました（現在は削除しています）。 結局、悩むくらいなら受けられるタイミングで受けておこう！　と決断し、申し込みました。 やった勉強方法 前述の通り、受験決定前に参考書を一冊買っていました。 インプレスの『徹底攻略 応用情報技術者教科書 令和5年度』の電子版です。 一通り読んでいましたが、もう一周読み直しました。 その後、 応用情報技術者試験過去問道場 を解いてはわからなかった問題に関する部分を参考書で再確認、解いては再確認……を繰り返しました。 勉強期間は10月からになるので長いですが、主に休みの日にだけ勉強してしていたので総勉強時間は65時間ほど（タイムトラッキングアプリで記録していた分）。 過去問道場で正答率75％ほどのレベルで、当日を迎えました。 試験当日の記録 普段より早起きが必要でしたが、前日に早寝できたので無事に起床。 パンとスープを朝食にして出発しました。自宅最寄り駅前のコンビニで昼食のおにぎりとタンパク質スティックを購入。 電車の遅れもな...
続きを読む

字が汚い人の手書きメモ利用術

サンプル数：1の個人の体験です。 小学生の時に硬筆・毛筆習字を習っていたにもかかわらず、私は字が汚いです。なんか…書く内容を考えていたら文字の形を意識するヒマなくないですか？ 基本的にタイピングのほうが楽だな～という意識の人間なのですが、手書きでメモを使うこともあります。私なりの手書きメモ活用方法を書いてみようと思います。 なお、スマホのフリック入力は苦手です。参考までに。 アイデア出し アイデア出しの時は紙のほうが書きやすいな、と思っています。連想したものを線でつなげたり、配置が自由なのがいいです。会社でのアイデア出しの場合、裏紙を使うことも多いです。 タブレットを普段から使う人ならタブレットに書き込めたりするんでしょうか。 ある程度出し切ってまとめた後は、改めてパソコン内で文章にしています。まとめたらメモは廃棄がマイルールです。まだ書けるスペースが広かったり手帳やノートに書いてたときは、まとめた部分はバツ印を上からつけて、終了済みとわかるようにしています。 タスクの書き出し これは最初からパソコン上ですることもあれば、まず紙に書き出すこともあります。 紙に書く場合は、たいてい初めての作業にまつわるタスク書き出しが多いです。「この作業を完了させるに必要なタスクは何か」という考えの書き出しという点では、前述のアイデア出しに似ているところがあるかもしれません。 仕事に関するタスクなら、書き出したあとは整理して社内でつかっているタスク管理ツールに記録します。プライベートでのなにかに関するタスクの場合、GoogleのKeepにチェックボックス形式でまとめることが多いです。 パソコン・スマホが使えないときのメモ これはもう見出しの通り、パソコン・スマホが使えないときのメモです。パソコンかスマホが使えるようになったらそちらに書き写します。 まとめ 紙に手書きでメモしたものは、パソコンで入力しなおすのが私の鉄則でした。そうしないと後で読み返したとき、自分でも解読できないという理由がかなり大きいです。 私と同じように、自分で自分の字が読めない・読みにくいという人には、デジタルで打ち直すということをおすすめします。スマホだと音声入力も結構便利です。 余談 後日、別記事でデジタルメモツールについて調べた結果や使っている感想を書いてみたいと思っています。 メモというよりログとしてが主な...
続きを読む

自己紹介＆このブログについて

自己紹介 ハンドルネーム 豆原カロ 本名じゃないので「豆原」は「まめばら」と読むつもりでつけました。でも変換は「まめはら」じゃないとできないです。お勉強ポイント+1 一般的な情報 1992年生まれ、女性。日本生まれ日本育ち。近畿民。 ざっくり履歴書 2011年に大学入学＆上京 2年目あたりからうまく過ごせず休学と復学を繰り返す 20代半ばで中途退学＆帰郷 アルバイトしたり病院に通ったり職業訓練を受けたりして過ごす 地元の中小企業でパートタイマーとして在職中 ほかの活動へのリンク Bluesky @anzen1ban Qiita @anzen1ban GitHub mamebara 小説家になろう 豆原カロ カクヨム 豆原カロ このブログについて 「仕事の学びも、資格取得も、趣味の活動も、毎日の体験も全部お勉強だ！」の精神で記録していきます。
続きを読む