テクニカルライティング勉強会をやってみた

この記事は [WESEEK Advent Calendar 2020](https://qiita.com/advent-calendar/2020/weseek) 14日目の記事です。

# テクニカルライティング勉強会をやってみた

社員のライティングスキルを底上げしよう！ということで、社内で行った「テクニカルライティング勉強会 ～今日から使える編～」の内容を紹介したいと思います。

ライティングに苦手意識を持っている人でも簡単に使えて、文章の質が1upすることまちがいなしです！

## はじめに
### テクニカルライティング技術とは

テクニカルライティング技術とは、「技術的な内容を正確かつ効率的に伝えるための文章作成技術」です。

### テクニカルライティングの歴史
- 1950年代：テクニカルライティングという言葉が使われるようになる
- 1970年代：洗濯機や冷蔵庫などの工業製品が普及。取扱説明書などを書くために、テクニカルライティング技術が必要となる
- 1980年代：コンピューターのビジネス利用が急増。必要性がさらに高まる
- 現在：ICTが発達。ビジネスに欠かせない技術として幅広い分野で活用されている

このように、テクニカルライティングは産業と共に発展してきました。

### なぜ文章を書く力は必要なのか？
文章を書く力がないとこんなことが起こるかもしれません。

- 操作マニュアルが分かりづらい　→　ユーザーが離れてしまう
- 仕様書に書かれた説明文が分かりづらい　→　誤認識があるまま実装されてしまう
- サポートメールの返信が分かりづらい　→　何度もやりとりが必要になる

エンジニアにとって文章を書くスキルはとても重要です。とはいえ、文法から勉強するのは大変ですよね。

そこで今回は、ポイントを絞って実例をあげながら文章を書くコツや注意点を紹介します。
## エンジニアが気をつけたい4つのこと
### 1. 漢字とひらがなを使い分ける
#### **いただきます or 頂きます ？**
- 「いただきます」は「…してもらう」の尊敬語

    ```
    例
    お送りしたメールをご確認いただけますでしょうか。
    ```

- 「頂きます」は「食う」「飲む」「もらう」の謙譲語

    ```
    例
    人気のレストランでコース料理を頂きました。
    お客様からお菓子を頂きました。
    ```

#### **できる or 出来る ？**
- 動詞、副詞として使う場合はひらがな

    ```
    例
    ページを閲覧できる
    できるだけ早く帰る
    ```

- 名詞として使う場合は漢字

    ```
    例
    上出来
    出来事
    出来の良い作品
    ```

#### **ください or 下さい ？**
- 「ください」はお願いするときなどに使う補助動詞 （英語の「please」）

    ```
    例
    ［編集］ボタンを押してください。
    お送りした資料をご覧ください。
    ```

- 「下さい」は「くれ」の丁寧語（英語の「give」）

    ```
    例
    この資料を３部下さい。
    ```

### 2. 一文一義
#### **1つの文が50文字程度以内におさめる**
- 「～し、」「～り、」「～ので、」を使って文を長くしない

#### **1つの文は1つの事柄を説明する**
- 「～が、」「～ので、」などでつなぐと、複数の内容を持つ文になりやすいので注意する

    ```
    例
    HOGEWIKIは簡単に使うことができ、誰でも手軽に編集することができますが、無料で利用することができます。
    ↓
    HOGEWIKIは
     ・ 簡単に使うことができます
     ・ 誰でも手軽に編集できます
     ・ 無料で利用できます
    ```

#### **1つの文は1つの行動を説明する**
- 順番が決まっている場合は、連続した番号を付けると手順の数が明確になる

    ```
    例
    デモサイトにアクセスして、デモサイトに掲載されているアカウントを確認し、ログインしてください。
    ↓
    1. デモサイトにアクセスします
    2. デモサイトに掲載されているアカウントを確認します
    3. 画面右上の[ログイン] ボタンを押します
    ```

### 3. 「する」を付けて動詞形にできる名詞に気をつける
#### **可能表現に気をつける**
- 一般動詞の可能表現は「～ことができる」を使用する
    - 見る、読む、食べる など
    
    ```
    例
    × 見られます
    ○ 見ることができます
    ```

- 動作名詞（サ変名詞）の可能表現は「～できる」を使用する
    - 編集、利用、設定、閲覧 など
    
    ```
    例
    × 編集することができます
    ○ 編集できます
    ```

#### **「する」を付けて動詞形にできる名詞に「行う」などを付けない**
- 動作名詞（サ変名詞）に、「行う」などを付けない
 
    ```
    例
    ×設定を行います
    ○設定します
    ```

### 4. 伝える相手のことを考えて書く
#### **読み手が理解できるやさしい言葉を使う**
- 簡単な言葉に言い換えられないか考える

    ```
    例
    押下
    ↓
    押す
    ```
    
- 用語の意味の変化に注意する

    ```
    例
    ○○をサポートする
    ↓
    「○○を支援する」
    「○○との組み合わせでも動作する」
    ```

- 注意文以外はなるべく肯定文で書く

    ```
    例
    × ログインしたままにしないでください
    ○ ログアウトしてください
    ```

#### **長音符号の表記が統一する**
#### **ルーター or ルータ ？**
長音の表記　～ 内閣告示の「外来語の表記」より一部抜粋 ～

```
英語の語末の ‐ｅｒ、‐ｏｒ、‐ａｒなどに当たるものは,原則としてア列の長音とし長音符号「ー」を用いて書き表す。
ただし,慣用に応じて「ー」を省くことができる。
```

- つまり、「router 」は、語尾が -er なので「ルーター」とのばすのが正式といえる
- ただし、「慣用に応じて「ー」を省くことができる。」とあるように技術文では長音を省略することが多いので、組織ごとに基準を定めることが大切

#### **記号・符号を適切に使って読みやすくする**
- 記号・符号の使い方は以下のように用途の指針が定められている

    | 記号・符号 | 呼び名 | 意味 |
    | ---------- | ------ | ---- |
    | （　）     | 丸括弧       | 直前の内容の説明、補足説明などに使う。     |
    | 「　」     | かぎ括弧       | 引用、語句の強調などに使う。     |
    | 『　』     | 二重かぎ括弧       | かぎ括弧の中にさらにかぎ括弧を入れるときや署名に使う。     |
    | ［　］     | 角括弧       | メニュー、ボタンなどの名称に使う。     |
    | ”　”       | 引用符       | 引用、語句の強調に使う。     |
    |  ：          | コロン       | 「機能：～」のようにして、意味や具体的な内容を示すときに使う。     |
    |  ＊          |  アスタリスク      | 注や参照の指示、注記、脚注に使う。     |
    日本語スタイルガイドより一部抜粋

## 最後に
今回は、簡単に実践できるライティングのTipsを紹介しました。みなさんが文章を書く時に、少しでも参考になれば幸いです。

参考文献：日本語スタイルガイド(第3版)(ISBN-13 : 978-4902820102)

※この記事は [WESEEK Tips wiki](https://tips.weseek.co.jp/) に 2020/12/13 に投稿された記事の転載です。
Tips wiki では、IT企業の技術的な情報やプロジェクトの情報を公開可能な範囲で公開してます。