たいやばなな

20代後半SE?SI?な自称エンジニアの日々の気づきや、試したことを種種雑多に雑記します。

Google先生が公開しているテクニカルライティング教材を読んでみた

f:id:tire-banana:20210509080259j:plain

Google先生ソフトウエアエンジニア・ソフトウエアエンジニアを目指す学生向けに公開しているテクニカルライティングの教材を読んでみました。今回は、筆者が重要だと思った事項を紹介したいと思います。

そもそもテクニカルライティングとは?

テクニカル・ライティングとは、狭義の意味では、『科学技術情報を正確かつ効果的に伝達するための文書作成技法』と定義付けられるでしょうhttp://www.logicalskill.co.jp/writing/tw.htm より

仕事に落とし込むと、仕様書、作業手順書、取説などの技術的な文章を書くことになるかと思います

1. 単語

google教材ページ: https://developers.google.com/tech-writing/one/words

当たり前ですが、文章は単語で構成されています。単語が正しく理解されないと、文章も正しく理解されなくなってしまいます。単語の使い方の見直しをして行こうというのがこの章の内容です。

以下要点をまとめながら紹介します。

用語

① 新しい用語や読者があまり使わない用語は以下のように「言葉の定義・説明」を文章に加える

  • 定義や説明を行った用語集が存在するなら、リンクを貼り付ける or オンラインじゃなかったらコピペする
  • 用語集がない場合は、文章中ではじめに出てきたタイミングで説明する
  • 大量に用語がある場合は用語集を作成する

② 用語は一貫性をもたせる、いきなり省略系・頭字語を使ったりしない。

頭字語(とうじご、英: acronym, 英: initialism)とは、主にヨーロッパ言語のアルファベットにおける略語の一種で、複数の単語から構成された合成語の頭文字を繋げて作られた語のこと。

省略や頭字語を使うときは宣言してから使うことを心がけます。登場回数が少ない単語は省略せずに書きます。

代名詞

総じて、対象となる名詞が明らかにならない場合は、代名詞は使わない

2. 短い文章

まずはじめに、Googleのテクニカルライティング教材で紹介されていた短い文章のメリットを紹介します。Googleのテクニカルライティング教材ではソフトウエアエンジニアにおけるコードの短さのメリットと比較していました。

相手が”人”か”コンピュータ”の違いで自分から言葉で相手へ伝えるというのは同じなのでポイントが共通するのは当たり前ですが、興味深いですね

■ コードと文章は短いほうがいい

★ コード(プログラミングコード)は短いほうが良い 以下が理由:

  • "他の人"が読みやすいから
  • 短いほうがメンテナンスしやすいから
  • 余計な行は”エラーの原因”だから

★ 文章は短い方が良い 以下が理由 :

  • "読者"が読みやすいから
  • 短い方がメンテナンスしやすいから
  • 余計な行は"読者の勘違いの原因"だから

具体的なポイントとしては

■ 一文には1つのアイデアしか入れない「1文 = 1意」に抑える

■ 長い一文はリスト(箇条書き)に変換する

長い一文の中に"接続詞"、"アイテムリスト"、"タスクリスト"が場合はリストに書き換える

↓**変換**

長い一文の中に以下がある場合はリストに書き換える
    - 接続詞
    - アイテムリスト
    - タスクリスト

★ リストに変換したい接続詞

または、もしくは、および、同様に
たり、とか、さらに

が出たら注意して、分が長くなる場合はリストに書き換えます。

3. リストの書き方

1.短い文章の最後で紹介したリストと表を書くポイントを紹介します。

★ リストの種類リストには2種類あり、違いは順番があるかどうかです。

  • 箇条書き(順番なしリスト)
  • 番号付きリスト(順番ありリスト)

リスト中の項目を並び替えても意味が変わらない場合は箇条書き項目の並び替えでリストの意味が変わる場合は番号付きリストにします。

★ リスト中の項目を並列に保つリスト中の項目は並列であり必要があります。名詞なら名詞。動作なら動作。

★ 番号付きリスト項目は命令形にする番号付きリストは作業者に操作を伝える作業手順を示す物が多いので命令形にして操作を明らかにします。

ドキュメント作成は基本

人によって多少はあるものの、仕事の基本はドキュメント作成かと思います。

作業をするにしても、作業指示を出すにしても、提案活動をするにしてもメール一つにしてもドキュメント作成が求められます。

いろいろな場面で必要となるドキュメント作成能力の向上が、生産性向上につながると考えられます。

また、わかりやすいドキュメントは、読む人の側にたって考えても理解が進みやすいというメリットが得られます。

一石二鳥ですね。

ではまた+++

Jcomp - jp.freepik.com によって作成された vintage 写真