テキストエディタはエンジニアが一生使う大切な仕事道具です。プログラミングを始めるなら、まずエディタの使い方を学びましょう。ここでは代表的なエディタであるVSCodeの使い方について徹底解説します。

開発するイメージ

Visual Studio Codeの使い方〈VSCode〉

テキストエディタ入門

技術ブログはエンジニアとして継続的に成長・セルフブランディングをする上で大切です。技術ブログとは何か、メリットや作り方・書き方など、《技術ブログの始め方》がゼロからわかります。

技術ブログのイメージ

エンジニアのための技術系ブログの始め方

技術ブログ入門

こんにちは、ぜに（[@zenizh]）です。これまで転職サイト・エージェントを利用しつつ、エンジニアとして3回の転職をしました。

転職をする前の自分は：

* 転職を考えてるんだけど、どのサイトに登録すればいいんだろう
* いつ登録すればいいんだろう
* そもそも転職サイト・エージェントって何をしてくれるんだろう

といった疑問がありました。

これについて、私の過去の転職経験と、採用担当者として上場企業・スタートアップでエンジニア採用に関わってきた経験をもとに、次について解説していきます：

* 転職サイト・エージェントとは何か
* いつ転職サイト・エージェントに登録すべきか
* 転職サイト・エージェントを選ぶ基準
* エンジニア向けの転職サイト・エージェント

この記事を読むことで、転職をするタイミングが来たときに、よりよい会社に・よりよい条件で転職できると思います。

::author

#### 目次

## 転職サイト・エージェントとは何か

:::illust
![転職エージェントのイメージ](//images.ctfassets.net/pppgbgujcovf/0pIfcm7lUFP1jhluQ77OL/f7c634cde8c890c697063c15e59fafa6/_____________________________________________.svg)
:::

転職サイト・エージェントとは、求人の検索〜転職先に入社するまで利用する、転職支援サービスのことをいいます。

これらサービスは無料で使えます。これは、利用者の転職が決まったときの成功報酬が売り上げとなるからです。

転職サイトとエージェントの違いは[こちらの記事](https://applis.io/posts/difference-between-job-site-and-job-agency)でも書きましたが、次の通りです：

| 種類 | 概要 | 例 |
| - | - | - |
| 転職サイト | 自分で転職活動をする | [転職ドラフト], Wantedly |
| 転職エージェント | 担当者が進めてくれる | [レバテックキャリア], [Kaguya] |

エンジニア向けの転職サービスは、転職エージェントが主流となっています。

### 転職までの流れ
ここで、転職までの流れを整理しておきます。転職サイト・エージェントを利用する・しないにかかわらず、求人〜転職先への入社までは、次のようになります：

| 順番 | 項目 | 内容 |
| :-: | - | - |
| 1 | **求人** | 企業からの求人を見つけます |
| 2 | **書類作成** | 職務経歴書などの書類を作ります |
| 3 | **応募** | 求人への応募や日程調整をします |
| 4 | **面接対策** | 面接の対策をします |
| 5 | **給与交渉** | 給与の交渉をします |
| 6 | **退職** | 内定したら今の職場を退職します |
| 7 | **入社** | 入社します |

転職エージェントは、この求人〜入社までを一緒に進めてくれるパートナーのようなイメージです。求人を見つけてくれるのはもちろん、書類の添削・面接練習や給与交渉のほか、退職手続き・入社後のフォローまでしてくれるところもあります。

一方で転職サイトはすべて自分でやることになります。よくいうとマイペースに転職を進めることができます。

## いつ転職サイト・エージェントに登録すべきか

:::illust
![サインアップのイメージ](//images.ctfassets.net/pppgbgujcovf/1pat5LRj0QehIMZh0DEBYQ/ef11e6536f64798196cd2b1a0969fd67/_______________________________________.svg)
:::

転職サイト・エージェントには、将来的な転職を少しでも考えているなら、早いうちに登録しておくべきです。

転職は、転職サービスに登録してから決まるまで3ヶ月〜1年はかかります。転職したい直前に登録しても、いい企業に出会える可能性は低いです。

逆に、転職意欲がまったくないのに登録するのも控えるべきです。転職エージェントはいい企業に出会える分、担当者とのやりとりがふえます。このやりとりがストレスになってしまいますね。

ほんの少しでも転職意欲があれば、転職サイト・エージェントに登録しておくといいです。継続的に相談しつつ、タイミングが来たときにいい企業を紹介してもらえます。

:::note
### 事例：筆者の場合
私は過去に転職活動をしたとき、まずたくさんの転職サイト・エージェントに登録しつつ、サービス内容や担当者との相性を基準に3つのサービスを残して他は退会しました。

今は転職意欲は高くないですが、そのときの転職意欲をもとに定期的に相談したりしています。このようなゆるい関係を作っておけるのも、転職エージェントの魅力だと思います。
:::

## 転職サイト・エージェントを選ぶ基準

:::illust
![選択肢のイメージ](//images.ctfassets.net/pppgbgujcovf/6y8f8yMs8AngxnqlmtJzhU/5d47ab5af55afc3ebaba534f54b90191/___________________________.svg)
:::

転職サイト・エージェントはたくさんありますが、エンジニアとして転職するなら次の5つの基準をもとにサービスを選ぶといいです：

* エンジニアに特化しているか
* サポート内容が充実しているか
* 働く場所は問題ないか
* 実績・信頼性はあるか
* レベルは合っているか

転職サイト・エージェントは、エンジニア以外にも総合職、医者・保育士向けなどいろんな種類があります。広く扱っているサービスより、エンジニアに特化している方が求人の質・担当者との相性がよくなります。

転職エージェントの中には、書類の添削・面接の練習をしてくれたり、中には退職・入社後のフォローをしてくれるところもあります。

働く場所については、首都圏に特化しているサービスもあれば地方に強いものもあります。最近だとリモートワークに力を入れているところもありますね。

レベルについては、CTO・リードエンジニアなどのハイクラス専門の転職サービスか、未経験も可能か。自分に合ったところを選びたいです。

## エンジニア向けの転職サイト・エージェント
上記基準をもとに、エンジニアが登録しておくべき転職サイト・エージェントを解説します。公式サイト内の情報のほか、私が実際に使ったり利用者に経験談をインタビューした上でまとめています。

ここでは次の7つの転職サイト・エージェントについて解説します。まずリストで示しつつ、各サービスについて個別に書いていきます：

1. [レバテックキャリア]
2. [Kaguya]
3. [転職ドラフト]
4. [JAC Recruitment]
5. [TechClipsエージェント]
6. [社内SE転職ナビ]
7. [IT求人ナビ 未経験] ☆未経験可

かなり厳選しているので、ここにある転職サイト・エージェントならどれに登録しても失敗しないと思います。公式サイトを見つつ、気になったところを登録〜相談してみるとよさそうです。

すべて無料で使えるので、自分に合ったところを厳選して長く付き合っていけるといいですね。

:::notice
### 公式サイトを確認してください

この記事の内容は執筆時点のものになります。最新の情報を反映するよう定期的に更新しますが、公式サイトを確認するようにしてください。
:::

### ① レバテックキャリア

[![レバテックキャリアのトップページ](//images.ctfassets.net/pppgbgujcovf/22dsoq1EtBzJYOwwR6vwVn/8c1344ccc3962848f32c81f902b52aa3/____________________________________________________________.png)][レバテックキャリア]
:img-caption{text="エンジニアが利用したい転職エージェントで1位を獲得"}

[レバテックキャリア]はエンジニア向けの代表的な転職エージェントです。日本マーケティングリサーチ機構の調査〈エンジニアが利用したい転職エージェント〉で1位を獲得しています。

5,000件以上の求人の中から、あなたに合った求人を提案してくれます。企業へのヒアリングを年間3,000回以上していて、最新の企業情報を把握した上で提案してくれるので、入社後の失敗を減らせます。

技術課題や面接対策、入社後のフォローなど、転職を一貫してサポートしてくれます。まずはじめに登録を検討したい転職エージェントですね。

| 項目 | 内容 |
| -: | - |
| エンジニア特化 | 特化している |
| サポート内容 | 書類添削・面接対策・給与交渉、退職・入社フォロー等 |
| 働く場所 | 関東・関西・九州 |
| 実績・信頼性 | サービス利用者20万人以上 |
| レベル | ハイクラスが中心 |

::button{label="レバテックキャリアにアクセスする" desc="無料で登録・相談できます" url="https://www.rentracks.jp/adx/r.html?idx=0.38812.291366.638.1054&dna=16106"}

### ② Kaguya

[![Kaguyaのトップページ](//images.ctfassets.net/pppgbgujcovf/5KcRVYvNoXBJ1rkVMYSdrL/fb62e32d460d9c43e6a39fdf092887e2/Kaguya______________________________.png)][Kaguya]
:img-caption{text="先端技術・イノベーション領域に強みをもつ"}

[Kaguya]は先端技術・イノベーション領域に強みをもつ転職エージェントです。東証一部上場企業子会社のメイテックが共同運営していて、信頼性があります。

メイテックは40年以上、数千社に対して技術を提供してきた実績があり、これを生かした転職相談が特徴です。技術に対する挑戦がしたいなら登録したいサービスですね。

| 項目 | 内容 |
| -: | - |
| エンジニア特化 | 特化している |
| サポート内容 | 面接対策・給与交渉 |
| 働く場所 | 幅広い |
| 実績・信頼性 | 年間8,000人が利用。東証一部上場企業子会社が共同運営 |
| レベル | 幅広い |

::button{label="Kaguyaにアクセスする" desc="無料で登録・相談できます" url="https://www.rentracks.jp/adx/r.html?idx=0.38812.291366.4375.6498&dna=88699"}

### ③ 転職ドラフト

[![転職ドラフトのトップページ](//images.ctfassets.net/pppgbgujcovf/4AlxuBBopxBiJJosbxbDN3/3ddfcb300a1388a416fdd3fc872cf127/___________________________________________________.png)][転職ドラフト]
:img-caption{text="企業から年収提示つきで指名される"}

[転職ドラフト]は転職サイトですが、企業から指名されるという特徴があります。レジュメを登録しておけば企業から指名されます。このとき年収も提示されるのが大きな強みですね。

指名はレジュメの内容によりますが、転職ドラフトではレジュメの作成を無制限にサポートしてもらえます。

平均年収アップ額が126万円と高く、実際に私も転職ドラフトを通して230万円も上げて転職したことがあります。自分で企業とやりとりする負担はありますが、たのしく転職ができると思います。

| 項目 | 内容 |
| -: | - |
| エンジニア特化 | 特化している |
| サポート内容 | レジュメ添削 |
| 働く場所 | 首都圏・関西地域が中心 |
| 実績・信頼性 | 東証一部上場企業のリブセンスが運営 |
| レベル | 幅広い |

::button{label="転職ドラフトにアクセスする" desc="無料で登録できます" url="https://px.a8.net/svt/ejp?a8mat=3HCD0M+EGCVHU+2OTA+HVFKY"}

### ④ JAC Recruitment

[![JAC Recruitmentのトップページ](//images.ctfassets.net/pppgbgujcovf/2cr8Qnvs2TvwLE1iKWXga0/101c17fd8dddb8e5dcd0e40ff03eec5d/JAC_Recruitment______________________________.png)][JAC Recruitment]
:img-caption{text="外資系企業などのグローバルな転職に強み"}

[JAC Recruitment]はロンドン発の転職エージェントで、外資系企業などのグローバルな転職に強みをもっています。800人の転職コンサルタントが在籍していて、1988年から累計43万人へのサポート実績があります。

書類の添削サポートは英文にも対応しているなど、外資系企業への転職を検討しているなら登録したいサービスですね。

| 項目 | 内容 |
| -: | - |
| エンジニア特化 | していない |
| サポート内容 | 書類添削・面接対策・給与交渉、退職フォロー |
| 働く場所 | 幅広い |
| 実績・信頼性 | 累計43万人への転職サポート。東証一部上場企業が運営 |
| レベル | 幅広い |

::button{label="JAC Recruitmentにアクセスする" desc="無料で登録・相談できます" url="https://www.rentracks.jp/adx/r.html?idx=0.38812.291366.1159.1870&dna=30223"}

### ⑤ TechClipsエージェント

[![TechClipsエージェントのトップページ](//images.ctfassets.net/pppgbgujcovf/016hC5ZyToenGwkGgkR3yQ/e363d8a2643840abae193698a6d30948/TechClips___________________________________________________.png)][TechClipsエージェント]
:img-caption{text="首都圏限定だが現役エンジニアによるサポートあり"}

[TechClipsエージェント]は現役のエンジニアによるサポートに強みをもつ転職エージェントです。首都圏（東京・神奈川・埼玉・千葉）に限定されますが、よい条件での転職が期待できます。

1,000社以上の求人を保有していますが、もしあなたにマッチする求人がないときは企業を新規開拓してくれます。働く場所に問題がなければ登録しておきたいサービスです。

| 項目 | 内容 |
| -: | - |
| エンジニア特化 | 特化している |
| サポート内容 | 書類添削・面接対策・給与交渉、退職フォロー |
| 働く場所 | 首都圏限定 |
| 実績・信頼性 | 現役エンジニアによるサポート |
| レベル | ハイクラスが中心 |

::button{label="TechClipsエージェントにアクセスする" desc="無料で登録・相談できます" url="//ck.jp.ap.valuecommerce.com/servlet/referral?sid=3574535&pid=887136202"}

### ⑥ 社内SE転職ナビ

[![社内SE転職ナビのトップページ](//images.ctfassets.net/pppgbgujcovf/1lDNgt6wNlTg7lI7WfY2SX/cad37f538ab1360ac4661f52f3121f60/______SE_____________________________________________.png)][社内SE転職ナビ]
:img-caption{text="自社サービス開発企業に限定"}

[社内SE転職ナビ]は自社サービス開発に限定した転職エージェントです。客先常駐がないので、働きやすい企業への転職ができます。

サポートも求人〜入社までをしっかり行ってくれます。担当者への相談はオンラインでも可能なので、ふだんの生活に支障がない形で転職活動を進められますね。

| 項目 | 内容 |
| -: | - |
| エンジニア特化 | 特化している |
| サポート内容 | 書類添削・面接対策・給与交渉、退職・入社フォロー |
| 働く場所 | 関東圏・関西圏 |
| 実績・信頼性 | 累計15,000人への転職サポート実績 |
| レベル | 幅広い |

::button{label="社内SE転職ナビにアクセスする" desc="無料で登録・相談できます" url="https://px.a8.net/svt/ejp?a8mat=3HCD0O+DML78Y+3IZO+HZ2R6"}

### ⑦ IT求人ナビ 未経験

[![IT求人ナビ 未経験のトップページ](//images.ctfassets.net/pppgbgujcovf/wcYeSWzmcWjfnm2uiQhNa/060a654014c93ae7a034c7c030dc9a98/IT_______________________________________________________.png)][IT求人ナビ 未経験]
:img-caption{text="転職エージェントにはめずらしく未経験に限定"}

[IT求人ナビ 未経験]は、未経験に限定している転職エージェントです。入社後にプログラミングやサーバー構築、運用などについて最大3ヶ月の研修がある企業を提案してもらえます。

他の転職サイト・エージェントでの転職がむずかしい場合も、このサービスなら転職できるかもしれません。あなたがエンジニア未経験なら検討したいサービスです。

| 項目 | 内容 |
| -: | - |
| エンジニア特化 | 特化している |
| サポート内容 | 給与交渉 |
| 働く場所 | 幅広い |
| 実績・信頼性 | エンジニアの登録者数8,000人 |
| レベル | 未経験限定 |

::button{label="IT求人ナビ 未経験にアクセスする" desc="無料で登録・相談できます" url="https://www.rentracks.jp/adx/r.html?idx=0.38812.291366.5897.8588&dna=109870"}

### まとめ：転職サイト・エージェント
以上です。長くなったので、もう一度リストでまとめておわりにします。どれも無料で利用できるので、登録・相談しつつあなたに合ったサービスを見つけていくといいですね。

* [レバテックキャリア]
* [Kaguya]
* [転職ドラフト]
* [JAC Recruitment]
* [TechClipsエージェント]
* [社内SE転職ナビ]
* [IT求人ナビ 未経験] ☆未経験可

## おわりに
転職サイト・エージェントは、将来的な転職を少しでも考えているなら、早めに登録しておくといいですね。

担当者と面談しつつ、自分に合うエージェントをいくつか厳選し、長期的な付き合いをすることで、転職について悩むことは少なくなると思います。

<div class="tracking-tags">
  <img src="https://www.rentracks.jp/adx/p.gifx?idx=0.38812.291366.638.1054&dna=16106" border="0" height="1" width="1">
  <img src="https://www.rentracks.jp/adx/p.gifx?idx=0.38812.291366.4375.6498&dna=88699" border="0" height="1" width="1">
  <img border="0" width="1" height="1" src="https://www16.a8.net/0.gif?a8mat=3HCD0M+EGCVHU+2OTA+HVFKY" alt="">
  <img src="https://www.rentracks.jp/adx/p.gifx?idx=0.38812.291366.1159.1870&dna=30223" border="0" height="1" width="1">
  <img src="//ad.jp.ap.valuecommerce.com/servlet/gifbanner?sid=3574535&pid=887136202" height="1" width="1" border="0">
  <img border="0" width="1" height="1" src="https://www11.a8.net/0.gif?a8mat=3HCD0O+DML78Y+3IZO+HZ2R6" alt="">
  <img src="https://www.rentracks.jp/adx/p.gifx?idx=0.38812.291366.5897.8588&dna=109870" border="0" height="1" width="1">
</div>

[@zenizh]: https://twitter.com/zenizh
[レバテックキャリア]: https://www.rentracks.jp/adx/r.html?idx=0.38812.291366.638.1054&dna=16106
[Kaguya]: https://www.rentracks.jp/adx/r.html?idx=0.38812.291366.4375.6498&dna=88699
[転職ドラフト]: https://px.a8.net/svt/ejp?a8mat=3HCD0M+EGCVHU+2OTA+HVFKY
[JAC Recruitment]: https://www.rentracks.jp/adx/r.html?idx=0.38812.291366.1159.1870&dna=30223
[TechClipsエージェント]: //ck.jp.ap.valuecommerce.com/servlet/referral?sid=3574535&pid=887136202
[社内SE転職ナビ]: https://px.a8.net/svt/ejp?a8mat=3HCD0O+DML78Y+3IZO+HZ2R6
[IT求人ナビ 未経験]: https://www.rentracks.jp/adx/r.html?idx=0.38812.291366.5897.8588&dna=109870

転職サイト・エージェントは、将来の転職を少しでも考えているなら早めに登録しておいた方がいいです。この記事では転職サイト・エージェントとは何か、選ぶ基準や登録すべきサービスについて解説します。よりよい会社・条件で転職できるようになります。

転職のイメージ

エンジニア転職で利用したいサイト・エージェント7つ【無料相談あり】

こんにちは、ぜに（[@zenizh]）です。2014年からフリーランスとして働きはじめ、会社員として働いていたときも副業サイト・エージェントを利用してきました。

フリーランスとして働く前は、どのサービスに登録すればいいのかわかりませんでした。そのときの自分に向けて、この記事では：

* フリーランス・副業を始めるにはどうすればいいか
* サイト・エージェントを選ぶ基準
* いつサイト・エージェントに登録すべきか
* 登録したいサイト・エージェント

について解説します。実際にこれらサービスを利用している人にインタビューしつつ、私が利用した経験もふまえてまとめています。

この記事を読むことで、あなたがフリーランス・副業をしたいときに、よりよい環境・条件で始められると思います。

::author

#### 目次

## フリーランス・副業を始めるにはどうすればいいか

:::illust
![始めるイメージ](//images.ctfassets.net/pppgbgujcovf/S16HCncS0Stt7DdJ5wUAC/ee0784238531a5143e3c8157c8d8b342/________________________.svg)
:::

フリーランス・副業をするには、まず〈案件・求人を見つけるサイト・エージェント〉に登録する必要があります。

こういったサイト・エージェントは、案件・求人の検索はもちろん、サービスによっては次のようなサポートもしてくれます：

* クライアントとの条件交渉・日程調整を担当してくれる
* 所得保障・福利厚生などのサービスがある
* 確定申告などの税務サポートがある

サイト・エージェント側は企業とのマッチング成立時の成功報酬が売り上げになっているので、あなたは無料でサービスを利用することができます。

## サイト・エージェントを選ぶ基準

:::illust
![チェックリストのイメージ](//images.ctfassets.net/pppgbgujcovf/2qulCTZ9kmq5RtP4VOCeGd/1a5fbcfebefb649f62c27241e9191380/_______________________________________.svg)
:::

フリーランス・副業のためのサイト・エージェントはたくさんあります。どういった基準で選べばいいのでしょうか。

これは、次の5つの基準をもとに選ぶといいです：

* 稼働日数は問題ないか
* 勤務地は問題はないか
* 営業代行はしてくれるか
* 福利厚生はあるか
* 信頼性・実績はあるか

稼働日数については、週1〜3日の案件を扱っているところもあれば、基本的に週5日の稼働が条件のところもあります。あなたの働き方に合わせて選ぶことが大切です。

勤務地については、フルリモートの案件もありますが、出社が必要なところもあります。働き方に問題がないかを確認する必要があります。

サイト・エージェントの中には担当者がつくサービスがあり、クライアントとの条件交渉・日程調整などを行ってくれるところもあります。あなたが企業とのコミュニケーションに抵抗があるなら、営業を代行してくれるところがよさそうです。

福利厚生はいろいろあって、たとえば案件が途切れたときの所得保障、確定申告などの税務サポートがあったりします。その他、保険料の補助など正社員のような働き方ができるところもあります。

何よりサービス提供者に信頼性・実績があるかどうか。この5つを見つつ、サイト・エージェントを選ぶと失敗しないと思います。

## いつサイト・エージェントに登録すべきか

:::illust
![時間のイメージ](//images.ctfassets.net/pppgbgujcovf/4LtlwFACnth1f9oMdubY2a/8ccedc5468ab8f2201d86ec6b2a25315/________________________.svg)
:::

フリーランス・副業として働きたいと少しでも考えているのなら、〈早いうちに登録しておいた方がいい〉です。

サイト・エージェントは登録したからといってすぐに仕事を受けられるわけではありません。案件・求人を見つけたり、クライアントとのやりとりが発生したりします。

とくに担当者がつくサービスの場合、まず担当者と面談して働き方や案件・求人について相談する必要があります。担当者と相性が合わない可能性もあります。

いくつかのサイト・エージェントに登録しつつ、あなたと相性の合うサービスを見つけた上で、あとはあなたのタイミングで仕事を始める。こういったイメージをもっておけばいいと思います。

## 登録したいサイト・エージェント
上で書いた基準を満たすサイト・エージェントについて解説していきます。

私が実際に利用した経験、利用者にインタビューした結果をふまえて書いています。たくさんのサイト・エージェントの中から厳選しているので、どれを選んでも失敗しないと思います。

まずリストで示し、ひとつずつ解説していきます：

1. [レバテックフリーランス]
2. [Midworks]
3. [ポテパンフリーランス]
4. [テックビズフリーランス]
5. [FREENANCE]

:::notice
### 公式サイトを確認してください

この記事の内容は随時更新しますが、サービスの内容が変わっている可能性があります。必ず公式サイトを確認するようにしてください。
:::

### ① レバテックフリーランス

[![レバテックフリーランスのトップページ](//images.ctfassets.net/pppgbgujcovf/1028Pe4wq0vgv2F6jv1sVt/ec1a5bc85e1b5ad71bcc149af20d1ff0/__________________________________________________________________.png)][レバテックフリーランス]
:img-caption{text="代表的なフリーランス・副業のためのサービス"}

[レバテックフリーランス]はレバレジーズ株式会社が運営するフリーランス向けのエージェントサービスです。日本マーケティングリサーチ機構によると登録者数が一位で、代表的なフリーランス・副業のためのサービスです。

担当者がついてくれて、営業代行やバックオフィス業務を全面サポートしてくれます。案件対応中も、要望に応じて次の案件を提案してくれるなど、働く以外のことすべてをやってくれる安心感があります。

運営元の信頼性・実績も十分で、フリーランスとして働くならまず登録を検討したいサービスです。

| 項目 | 内容 |
| -: | - |
| 稼働日数 | 週3〜5日 |
| 勤務地 | 関東・関西 |
| 営業代行 | 案件提案・日程調整・条件交渉・契約手続き等 |
| 福利厚生 | 健康・娯楽施設利用割引、税務サポート等 |
| 信頼性・実績 | レバレジーズが運営 |

::button{label="レバテックフリーランスにアクセスする" desc="無料で登録・相談できます" url="https://www.rentracks.jp/adx/r.html?idx=0.38812.291366.638.3602&dna=55857"}

### ② Midworks

[![Midworksのトップページ](//images.ctfassets.net/pppgbgujcovf/5vu38d8HQ3l202AlyYP1Tf/2deff1356ebb0fc4b8513871b59a37e0/Midworks______________________________.png)][Midworks]
:img-caption{text="各種保障が正社員並みに充実"}

[Midworks]は株式会社Branding Engineerが運営するフリーランス向け求人・案件サイトです。Midworksの特徴は〈正社員並みの保障〉で、賠償責任保障や税務保障、保険補助など各種保障が充実しています。

担当者がつき、相談後具体的な案件を提案してくれます。商談にも同行してくれて、条件交渉・契約手続きなども行ってくれます。

これだけのサポート内容で、手数料は20%以下となっています。クライアントからの発注金額も公開されていて、透明性という面でも信頼性のあるサービスです。

| 項目 | 内容 |
| -: | - |
| 稼働日数 | 週3〜5日 |
| 勤務地 | 関東・関西 |
| 営業代行 | 案件提案・日程調整・条件交渉・契約手続き等 |
| 福利厚生 | 健康・娯楽施設利用割引、税務サポート、保険料負担、報酬保障等 |
| 信頼性・実績 | Branding Engineerが運営 |

::button{label="Midworksにアクセスする" desc="無料で登録・相談できます" url="https://px.a8.net/svt/ejp?a8mat=3HCFD4+3QJZHU+3TVC+BX3J6"}

### ③ ポテパンフリーランス

[![ポテパンフリーランスのトップページ](//images.ctfassets.net/pppgbgujcovf/1fJaYDFWyQPISbbfznlghh/b10b885454beb6daf1edd26eb4cf0255/__________________________________________________________________.png)][ポテパンフリーランス]
:img-caption{text="有名なプログラミングスクールが運営"}

[ポテパンフリーランス]は有名なプログラミングスクールを運営している株式会社ポテパンが提供する案件・求人サイトです。担当者に相談しつつ、あなたに合った案件を提案してくれます。

税理士・フィナンシャルプランナーに税務・保健関連を相談できるなど、フリーランスとして働く上でのサポートがあり安心できます。

| 項目 | 内容 |
| -: | - |
| 稼働日数 | 週2〜5日 |
| 勤務地 | 関東・関西 |
| 営業代行 | 案件提案・担当者に相談可 |
| 福利厚生 | 税務サポート |
| 信頼性・実績 | 総利用者5,000人以上 |

::button{label="ポテパンフリーランスにアクセスする" desc="無料で登録・相談できます" url="https://px.a8.net/svt/ejp?a8mat=3HCFD4+4LIIYA+3UES+60WN6"}

### ④ テックビズフリーランス

[![テックビズフリーランスのトップページ](//images.ctfassets.net/pppgbgujcovf/75CEvBCAMSk952VqdPJV88/d644e0b851ea081d5ffb57e9438ecb87/_____________________________________________________________________.png)][テックビズフリーランス]
:img-caption{text="開業手続きなどをトータルでサポート"}

[テックビズフリーランス]は株式会社NKC ASIAが運営するフリーランス向けのエージェントサービスです。案件・求人の提案だけでなく、開業手続き・税務面など、フリーランスとして働く上でのいろんな悩みを担当者に相談できます。

また、UdemyやTechAcademyなどと提携していて、福利厚生も充実しています。記帳・確定申告も無料で、はじめてフリーランスとして働くなら登録しておくと安心できると思います。

| 項目 | 内容 |
| -: | - |
| 稼働日数 | 案件による |
| 勤務地 | 全国 |
| 営業代行 | 案件提案 |
| 福利厚生 | 税務サポート・提携サービスが豊富 |
| 信頼性・実績 | 案件発注者数10,000人 |

::button{label="テックビズフリーランスにアクセスする" desc="無料で登録・相談できます" url="https://www.rentracks.jp/adx/r.html?idx=0.38812.291366.4858.8561&dna=109625"}

### ⑤ FREENANCE

[![FREENANCのトップページ](//images.ctfassets.net/pppgbgujcovf/5RMrRGP7o5dqUu6Mwg5GoP/1d2f51d9602e790446533594805f9f9b/FREENANC______________________________.png)][FREENANCE]
:img-caption{text="口座を指定するだけで各種サポートを受けられる"}

[FREENANCE]は案件・求人サイトではなく、無料で利用できる〈お金と保険のサービス〉です。GMOグループのGMOクリエイターズネットワーク株式会社が運営しています。

FREENANCEで口座を開設し、フリーランスでの収入の入金先をFREENANCE口座にすることで、次のサポートを受けられます：

* 業務中の事故・情報漏洩・納期遅延等を補償
* 即日払いに対応
* 病気等で働けなくなったときに1年間所得を補償

無料で開設・利用でき、各種サポートを受けられるので、フリーランスとして働くなら登録しておきたいサービスです。ふだん使いの口座への出金も、週に一回・手数料無料で行われます。

::button{label="FREENANCEにアクセスする" desc="無料で利用できます" url="https://px.a8.net/svt/ejp?a8mat=3HCFD4+4UG10Y+47L8+5YRHE"}

### まとめ：登録したいサイト・エージェント

長くなったので、前述したリストを再掲します：

1. [レバテックフリーランス]
2. [Midworks]
3. [ポテパンフリーランス]
4. [テックビズフリーランス]
5. [FREENANCE]

公式サイトを見て、気になったサイト・エージェントにいくつか登録してみてください。担当者と話しつつ、あなたに合うサイト・エージェントを1〜2つ見つけられるといいですね。

<div class="tracking-tags">
  <img src="https://www.rentracks.jp/adx/p.gifx?idx=0.38812.291366.638.3602&dna=55857" border="0" height="1" width="1">
  <img border="0" width="1" height="1" src="https://www12.a8.net/0.gif?a8mat=3HCFD4+3QJZHU+3TVC+BX3J6" alt="">
  <img border="0" width="1" height="1" src="https://www14.a8.net/0.gif?a8mat=3HCFD4+4LIIYA+3UES+60WN6" alt="">
  <img src="https://www.rentracks.jp/adx/p.gifx?idx=0.38812.291366.4858.8561&dna=109625" border="0" height="1" width="1">
  <img border="0" width="1" height="1" src="https://www19.a8.net/0.gif?a8mat=3HCFD4+4UG10Y+47L8+5YRHE" alt="">
</div>

[@zenizh]: https://twitter.com/zenizh
[レバテックフリーランス]: https://www.rentracks.jp/adx/r.html?idx=0.38812.291366.638.3602&dna=55857
[Midworks]: https://px.a8.net/svt/ejp?a8mat=3HCFD4+3QJZHU+3TVC+BX3J6
[ポテパンフリーランス]: https://px.a8.net/svt/ejp?a8mat=3HCFD4+4LIIYA+3UES+60WN6
[テックビズフリーランス]: https://www.rentracks.jp/adx/r.html?idx=0.38812.291366.4858.8561&dna=109625
[FREENANCE]: https://px.a8.net/svt/ejp?a8mat=3HCFD4+4UG10Y+47L8+5YRHE

エンジニアとしてフリーランス・副業を始めるには、サイト・エージェントに登録する必要があります。この記事ではサービスを選ぶ基準をもとに、登録したいサービスを解説します。フリーランス・副業をよりよい環境・条件で始められるようになります。

フリーランス・副業のイメージ

【エンジニア】副業するなら登録しておきたいサイト・エージェント5つ

こんにちは、ぜに（[@zenizh]）です。2012年にプログラミング教育事業で起業し、今はボランティアでプログラミングスクールに通っている人の技術メンターをしたりしています。

プログラミングを早く・効率的に学ぶにはプログラミングスクールに通った方がいいですが、候補がたくさんあってどこがいいか迷うと思います。

この記事では：

* プログラミングスクールとは何か
* プログラミングスクールで学ぶべきかどうか
* プログラミングスクールを選ぶ基準
* 選ぶべきプログラミングスクール

について解説します。この記事を読むことで〈プログラミングスクールに通うべきかどうか〉がわかり、学ぶと決めたときに〈どこを選べばいいか〉がわかります。

::author

#### 目次

## プログラミングスクールとは何か

:::illust
![説明のイメージ](//images.ctfassets.net/pppgbgujcovf/5ap9ChzRELpcHxUppFws1k/2ac6403d16e0670fc7e1e0a17688fa4a/________________________.svg)
:::

プログラミングスクールは〈エンジニアになるために必要なスキルを効率よく身につけるためのサービス〉です。

スキルとは、例えばHTML/CSSやRuby、Git、データベースなどですね。これらを学習しつつ、メンターと呼ばれる人にチャット・ビデオ通話で相談していきます。

学習が完了したら、転職支援を受けつつエンジニアとしての転職をめざします。

学ぶ場所はオンラインが基本で、中には通学ができるプログラミングスクールもあります。学習時間は3ヶ月〜が基本で、費用は20〜60万円ほどかかります。

## プログラミングスクールで学ぶべきかどうか

:::illust
![考えごとのイメージ](//images.ctfassets.net/pppgbgujcovf/3kFT3fJbrOIYt6eP3hpSPe/ae28413877d5148ede449f2e5c4e7c3c/_________________________________.svg)
:::

プログラミングスクールは、〈より早くエンジニアとして働き始めたい〉なら通うことを検討するといいです。

エンジニアとして働くために必要なスキルはいろいろあります。例えば上で書いたHTML/CSSやRubyなどですね。

ただ、何より大切なスキルは〈問題解決能力〉です。

プログラミングをしようとすると、いろんな問題が発生します。環境構築がうまくいかなかったり、コードの記述が間違っていたり。こういった問題を特定して、解決するための考え方が問題解決能力です。

問題解決能力は、エンジニアとして働く上で必要不可欠なスキルです。

この能力は独学でも身につけることができます。実際に独学でエンジニアをやっている人もたくさんいて、私も独学でエンジニアになりました。

ただ、独学だと問題が起きたときに〈それが問題であることを認識しづらい〉です。もちろん、解決のためのアドバイスももらえません。

プログラミングスクールだと、独学より早く・効率的に問題解決能力を高めることができます。時間をお金で買うイメージですね。

もし早くエンジニアになりたいのであれば、プログラミングスクールに通うことを検討するといいと思います。

## プログラミングスクールを選ぶ基準

:::illust
![チェックリストのイメージ](//images.ctfassets.net/pppgbgujcovf/2qulCTZ9kmq5RtP4VOCeGd/1a5fbcfebefb649f62c27241e9191380/_______________________________________.svg)
:::

プログラミングスクールで学ぶとして、どこを選べばいいのか。これは、次の基準をもとに決めるといいです：

* 学べる技術は何か
* 学び方はどうか
* 学習期間はどれくらいか
* 転職支援はあるか
* 費用はどれくらいか
* 保証制度はあるか
* 実績・信頼性はあるか

この基準をもとに、次でプログラミングスクールを解説していきます。

## 選ぶべきプログラミングスクール
上の基準をもとに、プログラミングスクールを解説していきます。解説するのは次の6つです：

1. [TechAcademy]
2. [ポテパンキャンプ]
3. [DMM WEBCAMP]
4. [フィヨルドブートキャンプ]
5. [RUNTEQ]
6. [DIVE INTO CODE]

私はプログラミングスクールに通っている人の技術メンターをしていて、生徒の方にヒアリングしつつまとめています。

たくさんのプログラミングスクールから厳選しているので、どこを選んでも失敗しないと思います。大切なのは〈あなた自身が主体的に学べるかどうか〉なので、実績・信頼性のあるところであれば、あとは予算感などで選べばいいと思います。

費用面などをもとに、公式サイトを見て気になったところを無料相談して、最終的にひとつを決められるといいですね。

:::notice
### 公式サイトを確認してください

この記事の内容は最新のものになるよう随時更新していますが、費用などは公式サイトを確認の上で申し込んでください。
:::

### ① TechAcademy

[![TechAcademyのトップページ](//images.ctfassets.net/pppgbgujcovf/6HssPWwderErdUJ1yD5aqO/ed9007a6eee8a957f3daade1b2dea159/TechAcademy______________________________.png)][TechAcademy]
:img-caption{text="受講者数第一位の代表的なプログラミングスクール"}

[TechAcademy]はキラメックス株式会社が運営する、受講者数が第一位の代表的なプログラミングスクールです。〈エンジニア転職保証コース〉はプログラミング未経験の初心者でも12週間で東京のIT企業への転職をめざせます。

TechAcademyは実績・信頼性があり、学習・転職のサポート体制もしっかりしていて、費用も他のプログラミングスクールに比べて安い水準にあります。まず初めに検討したいサービスです。

| 項目 | 内容 |
| -: | - |
| 学べる技術 | Java, Ruby on Rails, Python等 |
| 学び方 | オンライン |
| 学習期間 | 12週間 |
| 転職支援 | キャリア相談・書類添削・日程調整・面接後フォロー等 |
| 転職保証 | 内定が出ない場合に全額返金 |
| 費用 | 327,800円 |
| 実績・信頼性 | 受講生30,000人 |

::button{label="TechAcademyにアクセスする" desc="無料カウンセリングあり" url="https://px.a8.net/svt/ejp?a8mat=3HDXE2+EHJQPE+3GWO+BW8O2&a8ejpredirect=https%3A%2F%2Ftechacademy.jp%2Fpro%2Fjobchange-bootcamp"}

### ② ポテパンキャンプ

[![ポテパンキャンプのトップページ](//images.ctfassets.net/pppgbgujcovf/33K9zat1CN3dPFXvQYD8LT/6c82ba98d184bcf240dec96511201972/_______________________________________________________________.png)][ポテパンキャンプ]
:img-caption{text="転職サポートに定評"}

[ポテパンキャンプ]は株式会社ポテパンが運営するプログラミングスクールです。同社は転職・フリーランスなどエンジニアの人材事業を広く手がけていて、転職サポートに定評があります。

Railsキャリアコースは5ヶ月間で、HTML/CSSやJavaScriptの他、Ruby on RailsをRubyの基礎から身につけることができます。入学時のスキルによって期間・料金が少なくなるので、無料相談で確認してみるといいですね。

| 項目 | 内容 |
| -: | - |
| 学べる技術 | Ruby on Rails, HTML/CSS, JavaScript等 |
| 学び方 | オンライン |
| 学習期間 | 20週間 |
| 転職支援 | キャリア相談・書類添削等 |
| 転職保証 | なし（無期限の転職サポートあり） |
| 費用 | 440,000円 |
| 実績・信頼性 | 10,000人以上の転職をサポート |

::button{label="ポテパンキャンプにアクセスする" desc="無料カウンセリングあり" url="https://px.a8.net/svt/ejp?a8mat=3HDXE2+FMMNG2+3UES+BZ0Z6"}

### ③ DMM WEBCAMP

[![DMM WEBCAMPのトップページ](//images.ctfassets.net/pppgbgujcovf/60sNDa7snrA2qYSE9hdXmO/91eabe9373e29b705715b1abe979c767/DMM_WEBCAMP______________________________.png)][DMM WEBCAMP]
:img-caption{text="DMMグループが運営"}

[DMM WEBCAMP]はDMMグループの株式会社インフラトップが運営するプログラミングスクールです。PROコースでは、今の仕事を続けながらエンジニア転職をめざすことができます。

サービスの企画・設計・開発・リリースを、メンターのサポートを受けつつ学べます。開発したサービスはポートフォリオになるので、転職にも役立ちます。その他、発展的な学習フェーズとしてAWSを学ぶこともできます。

| 項目 | 内容 |
| -: | - |
| 学べる技術 | Ruby on Rails, HTML/CSS, Git等 |
| 学び方 | オンライン |
| 学習期間 | 12週間/16週間（選択可） |
| 転職支援 | キャリア相談・書類添削・面接対策等 |
| 転職保証 | なし（最長1年間の転職サポートあり） |
| 費用 | 624,800円〜 |
| 実績・信頼性 | DMMグループが運営 |

::button{label="DMM WEBCAMPにアクセスする" desc="無料カウンセリングあり" url="https://www.rentracks.jp/adx/r.html?idx=0.38812.291366.2373.3633&dna=56277"}

### ④ フィヨルドブートキャンプ

[![フィヨルドブートキャンプのトップページ](//images.ctfassets.net/pppgbgujcovf/2C5kkPFLVc2s6zT0LYYZcS/62fd3c6f71c0ed67c623529ef428b095/___________________________________________________________________________.png)][フィヨルドブートキャンプ]
:img-caption{text="月額制・有名なメンターが在籍"}

[フィヨルドブートキャンプ]は株式会社フィヨルドが運営するプログラミングスクールです。メンターとしてRubyコミュニティで有名な方が多く在籍しています。[学習内容](https://bootcamp.fjord.jp/practices)を見てもわかる通り、Rubyを中心にエンジニアとして必要なスキルを学べます。

生徒の方にヒアリングしたところ、かなりの自走力が求められる・公式サイトにある900時間での卒業は難しいようです。ただ月額制で費用も抑えられるので、主体的に学びたい方にとっては最高の環境だと思います。

| 項目 | 内容 |
| -: | - |
| 学べる技術 | Ruby on Rails, HTML/CSS, Linux, テスト等 |
| 学び方 | オンライン |
| 学習期間 | 900時間〜 |
| 転職支援 | アドバイスあり |
| 転職保証 | なし |
| 費用 | 29,800円/月 |
| 実績・信頼性 | 多くの有名なRubyエンジニアの方が在籍 |

::button{label="フィヨルドブートキャンプにアクセスする" desc="3日間のお試し期間あり" url="https://bootcamp.fjord.jp/"}

### ⑤ RUNTEQ

[![RUNTEQのトップページ](//images.ctfassets.net/pppgbgujcovf/4ckJifmCWPXzdp3vlMpNDW/2444a00f80c36a149f29c14fba6d07b8/RUNTEQ______________________________.png)][RUNTEQ]
:img-caption{text="Webアプリ開発の総合的なスキルを身につけられる"}

[RUNTEQ]は株式会社スタートアップテクノロジーが運営するプログラミングスクールです。学習の他にER図の作成・画面設計、実装などのサポートを受けられます。

今の技術レベルに応じて3つの学習コースから選べます。採用技術としてVue.jsを学べるのも特徴的で、Webアプリケーション開発の総合的なスキルを身につけられます。

| 項目 | 内容 |
| -: | - |
| 学べる技術 | Ruby on Rails, Vue.js等 |
| 学び方 | オンライン |
| 学習期間 | 780〜1,000時間 |
| 転職支援 | キャリア相談・書類添削・面接対策等 |
| 転職保証 | なし |
| 費用 | 327,800円〜 |
| 実績・信頼性 | 生徒によるポートフォリオ多数 |

::button{label="RUNTEQにアクセスする" desc="無料キャリア相談あり" url="https://px.a8.net/svt/ejp?a8mat=3HDXE2+EJC1IQ+4RCW+5YJRM"}

### ⑥ DIVE INTO CODE

[![DIVE INTO CODEのトップページ](//images.ctfassets.net/pppgbgujcovf/6mOtoP7BZfJjyqfcRJjXg/6a5597dc3792d8c79bea5f6b1b2544e0/DIVE_INTO_CODE______________________________.png)][DIVE INTO CODE]
:img-caption{text="経済産業省の教育訓練講座に指定"}

[DIVE INTO CODE]は株式会社DIVE INTO CODEが運営するプログラミングスクールです。〈問題解決能力〉を高めることにフォーカスしていて、エンジニアとしての力を身につけることができます。

卒業生の方と一緒に働いたことがありますが、問題解決能力や技術に対する習得意欲が高いことにおどろいた記憶があります。

Webエンジニアコース（フルタイム）は経済産業省の〈専門実践教育訓練指定講座〉に指定されていて、最大45万円のキャッシュバックを受けることもできます。

| 項目 | 内容 |
| -: | - |
| 学べる技術 | Ruby on Rails, HTML/CSS, JavaScript等 |
| 学び方 | オンライン |
| 学習期間 | 4ヶ月間 |
| 転職支援 | 書類添削 |
| 転職保証 | なし |
| 費用 | 647,800円 |
| 実績・信頼性 | 転職実績多数, 経済産業省による認定 |

::button{label="DIVE INTO CODEにアクセスする" desc="無料説明会あり" url="https://www.rentracks.jp/adx/r.html?idx=0.38812.291366.5996.8676&dna=110895"}

### まとめ：プログラミングスクール

長くなったので、プログラミングスクールのリストを再掲します：

1. [TechAcademy]
2. [ポテパンキャンプ]
3. [DMM WEBCAMP]
4. [フィヨルドブートキャンプ]
5. [RUNTEQ]
6. [DIVE INTO CODE]

学習内容やサポート内容が変わってくるので、公式サイトを見つつ気になったところを無料相談・体験を申し込んでみるといいと思います。

[@zenizh]: https://twitter.com/zenizh
[TechAcademy]: https://px.a8.net/svt/ejp?a8mat=3HDXE2+EHJQPE+3GWO+BW8O2&a8ejpredirect=https%3A%2F%2Ftechacademy.jp%2Fpro%2Fjobchange-bootcamp
[ポテパンキャンプ]: https://px.a8.net/svt/ejp?a8mat=3HDXE2+FMMNG2+3UES+BZ0Z6
[DMM WEBCAMP]: https://www.rentracks.jp/adx/r.html?idx=0.38812.291366.2373.3633&dna=56277
[フィヨルドブートキャンプ]: https://bootcamp.fjord.jp/
[RUNTEQ]: https://px.a8.net/svt/ejp?a8mat=3HDXE2+EJC1IQ+4RCW+5YJRM
[DIVE INTO CODE]: https://www.rentracks.jp/adx/r.html?idx=0.38812.291366.5996.8676&dna=110895

<div class="tracking-tags">
  <img border="0" width="1" height="1" src="https://www16.a8.net/0.gif?a8mat=3HDXE2+EHJQPE+3GWO+BW8O2" alt="">
  <img border="0" width="1" height="1" src="https://www11.a8.net/0.gif?a8mat=3HDXE2+FMMNG2+3UES+BZ0Z6" alt="">
  <img src="https://www.rentracks.jp/adx/p.gifx?idx=0.38812.291366.2373.3633&dna=56277" border="0" height="1" width="1">
  <img border="0" width="1" height="1" src="https://www18.a8.net/0.gif?a8mat=3HDXE2+EJC1IQ+4RCW+5YJRM" alt="">
  <img src="https://www.rentracks.jp/adx/p.gifx?idx=0.38812.291366.5996.8676&dna=110895" border="0" height="1" width="1">
</div>

プログラミングを効率的に学ぶにはプログラミングスクールに通った方がいいですが、候補がたくさんあってどこがいいか迷うと思います。この記事で〈プログラミングスクールに通うべきかどうか〉がわかり、学ぶと決めたときに〈どこを選べばいいか〉がわかります。

スクールのイメージ

プログラミングスクールで選びたいおすすめ6つ【効率的に学べる】

先日、[3級 テクニカルライティング試験](https://www.jtca.org/certificate_exam/exam_writing_b.html)を受験しました。

私はテクニカルライターとして働いていて、仕事でドキュメントを書いています。テクニカルライティング試験は仕事の役に立ちそうで、受験してよかったと感じています。

この記事では、テクニカルライティング試験の概要や受けるべき人、勉強方法などをまとめています。よかったら参考にしてください。

::author

#### 目次

## 3級 テクニカルライティング試験とは

3級 テクニカルライティング試験は、テクニカルコミュニケーター協会が実施している検定試験です。

この試験は、日本語の文章作成に関する技術について、客観的に評価するものです。この試験に合格することで、文章を作成するための一定の能力がある、とみなされることになります。

例えばドキュメントや議事録、メールなどの文章を書くときに、より読みやすく、分かりやすく書けるようになります。実際に、私もふだんの業務の役に立っています。

## 試験の立ち位置

テクニカルコミュニケーター協会は、[テクニカルコミュニケーション技術検定試験](https://www.jtca.org/certificate_exam/)を策定しています。そのうちの第一段階が、3級 テクニカルライティング試験になります。

テクニカルコミュニケーション技術検定試験は、次の各試験で構成されています。

| 級 | 試験 |
| --- | --- |
| 3級 | テクニカルライティング試験 |
| 2級 | 使用情報制作ディレクション試験 |
| 2級 | 使用情報制作実務試験 |
| 1級 | （詳細を検討中） |

1級については、その詳細を検討中とのことらしいです。テクニカルライティング試験は、3級という名前こそついていますが、ことテクニカルライティングに関しては最上位の試験となります。

## 誰が受けるべきか

3級 テクニカルライティング試験は、文章の作成を仕事で行なっている人であれば受けるべきだと思っています。

テクニカルライターはもちろん、開発ドキュメントを書くエンジニアなどが当てはまります。それ以外の人でも、議事録やメールなどの文章を書く機会がある人は、テクニカルライティング試験を受けることで、仕事の役に立ちます。

例えば、テクニカルライティング試験のための勉強をする過程で、次のようなことが身に付きます。

- 漢字とひらがなの使い分け
- 算用数字と漢数字の使い分け
- 句読点、括弧などの記号の使い方
- 箇条書きにおける並べ方
- 著作権法に基づく引用のしかた

個人的な意見としては、日本語の文章作成に関わるすべての人に取得してほしい検定試験です。

## 試験の概要

3級 テクニカルライティング試験は、年に2回開催されています。学科試験で、選択式と記述式の2部構成です。

| 試験科目 | 時間 | 概要 |
| --- | --- | --- |
| 選択式 | 50分 | 4択から選ぶ |
| 記述式 | 50分 | 文章を書く |

記述式については、公式サイトで公開されている記述問題の例題にもありますが、ゼロベースで書くのではなく、元となる文章を読みやすくするにはどうするか？といった形式の問題になります。

各100点満点で採点され、一定以上の点数で合格となるようです。詳しくは、[公式サイト](https://www.jtca.org/certificate_exam/exam_writing_b.html)をご覧ください。

## 勉強方法

:::notice
### 注意事項

ここでは、公式サイトで提供されている情報の範囲で勉強方法をまとめます。具体的な試験内容については書きません。また、ご連絡いただいても回答できないことをご理解ください。
:::

3級 テクニカルライティング試験の勉強方法について、まず事前準備からまとめます。結論からいうと[日本語スタイルガイド（第3版）]を購入し、[受験対策セミナー](https://www.jtca.org/certificate_exam/exam_seminar_01.html)に申し込みます。この2つは必須になります。

| 手順 | 概要 | 時間（目安） |
| --- | --- | --- |
| 1 | 日本語スタイルガイドを購入する | 5分 |
| 2 | 受験対策セミナーに申し込む | 15分 |

日本語スタイルガイドは、テクニカルライティング試験を実施しているテクニカルコミュニケーター協会が発行しています。受験対策セミナーも、日本語スタイルガイドを用いて出題範囲を解説します。

日本語スタイルガイドや受験対策セミナーでは練習問題があり、この2つを行うことで合格率が大きく上がります。もちろん、文章を作成する能力の向上にもつながります。

勉強方法について、その中心となるのは、やはり受験対策セミナーです。セミナーを受講し、その要点をまとめます。なぜなら、要点をまとめる過程で、その知識を得ることができるからです。

要点をまとめた上で、要点を確認したり、練習問題を解く・復習することで、能力として定着していきます。

| 手順 | 概要 | 時間（目安） |
| --- | --- | --- |
| 3 | 日本語スタイルガイドに軽く目を通す | 1時間 |
| 4 | 受験対策セミナーを受講する | 3時間 |
| 5 | セミナーの要点をまとめる | 4時間 |
| 6 | 要点を確認する | 2時間 |
| 7 | 日本語スタイルガイドを読む | 4時間 |
| 8 | 練習問題を解く・復習する | 2時間 |

練習問題は、受験対策セミナー中に使用する問題、公式サイトで公開されている記述問題の例題、日本語スタイルガイド内の練習問題などがあります。過去問はありません。

勉強時間は、上記の例でいうと16時間ですが、多めに見積もって20〜40時間ほどあればよいでしょう。時間がある分だけ、手順6〜8を繰り返すとよさそうです。

## 試験の難易度

3級 テクニカルライティング試験の合格率は、[公式サイト](https://www.jtca.org/certificate_exam/exam_result_01.html)に掲載されています。公式サイトによると、2022年2月27日に実施した試験の合格率は58.2%とのことです。

合格率としては高めですが、個人的には結構難しく感じました。

選択式問題については、上記の勉強方法で問題ありませんが、厄介なのが記述式です。記述式は、練習問題を見ても分かる通り、文章の作成というよりは基本的な読解力が求められます。つまり、対策が難しいです。

また、記述式は問題の量が多く、とにかく時間が足りませんでした。これは、練習問題を早く解く練習をするとよさそうです。

## 関連記事

他にも、受験した方の体験談があります。3級 テクニカルライティング試験を受験する際の参考にしてみてください。

- [３級テクニカルライティング試験の合格体験記](https://qiita.com/pyon_kiti_jp/items/9c558232b7fdf7fc976e)
- [TC技術検定３級を受けてみた](https://note.com/tech_write/n/nb32c212d250b)

## まとめ

3級 テクニカルライティング試験は、日本語の文章作成に関する技術を客観的に評価するものです。取得のための勉強をすることで、より読みやすい、分かりやすい文章が書けるようになります。

[日本語スタイルガイド（第3版）]と受験対策セミナーをもとに勉強をすることで、合格につながります。ぜひ参考にしてみてください。

[日本語スタイルガイド（第3版）]: //af.moshimo.com/af/c/click?a_id=2464392&amp;p_id=170&amp;pc_id=185&amp;pl_id=4062&amp;url=https%3A%2F%2Fwww.amazon.co.jp%2Fdp%2F4902820102

<div class="tracking-tags">
  <img src="//i.moshimo.com/af/i/impression?a_id=2464392&amp;p_id=170&amp;pc_id=185&amp;pl_id=4062" alt="" width="1" height="1" style="border: 0px;" />
</div>

私はテクニカルライターとして働いていて、仕事でドキュメントを書いています。テクニカルライティング試験は仕事の役に立ちそうで、受験してよかったと感じています。この記事では、テクニカルライティング試験の概要や受けるべき人、勉強方法などをまとめています。よかったら参考にしてください。

試験のイメージ

3級 テクニカルライティング試験の概要や勉強方法など

エンジニアにとって、分かりやすい開発ドキュメントを書くには、テクニカルライティングのスキルが重要になります。

私はエンジニアからテクニカルライターになりました。この経験をもとに、テクニカルライティングにはどんなスキルが重要なのか、どう身に付ければよいのかをまとめます。

::author

#### 目次

## テクニカルライティングとは

テクニカルライティングとは、

> ある製品について、利用者に分かりやすく伝えること

をいいます。この定義については、「[テクニカルライティングとは何か](/posts/what-is-technical-writing)」をご覧ください。

テクニカルライティングの例としては、次のようなものがあります。

* 電子レンジの取扱説明書
* APIリファレンス
* 社内の開発ドキュメント

こういった広い意味での製品について、利用者に分かりやすく伝えることがテクニカルライティングになります。

## テクニカルライティングに重要なスキル

テクニカルライティングをする上では、次の3つのスキルが重要になります。この定義については、「[テクニカルライターにとって重要なスキル](/posts/important-skills-for-technical-writer)」をご覧ください。

* 製品に関する技術力
* 分かりやすく伝える文章作成力
* 文章に関わる人とのコミュニケーション力

エンジニアの方であれば、技術力とコミュニケーションについては、ふだんの業務で身に付くと思います。ただ、文章作成力については、自分で努力する必要が出てきます。

この文章作成力を身に付ける方法について、次に説明していきます。

## テクニカルライティングのスキルを高める方法

テクニカルライティングのスキルのうち、自分で身に付けるべき「文章作成力」を高めるには、技術ブログを書くことがもっとも効率がよいと考えています。

技術ブログとは、技術的な内容についてブログに書くことです。例えば、プログラミングのことや、エラーの解決方法などを書きます。

なぜ技術ブログがよいかというと、文章作成力は繰り返し書かないと身に付かないためです。技術ブログは、自分のペースで、繰り返し書けるというメリットがあります。

このときに重要なのは、ただ書くのではなく、「読者に伝えることを意識して書く」ことです。

はじめはうまく書けないかもしれませんが、これはまったく問題がありません。書き続けることで、次第に文章作成力が身に付いていきます。

技術ブログの始め方について詳しくは、「[技術ブログ入門](/guides/tech-blog)」をご覧ください。また、技術系の文章の書き方について詳しくは、次の記事をご覧ください。

* [開発ドキュメントの書き方](/posts/how-to-write-document)
* [開発ドキュメントの文章における表現方法](/posts/expressions-in-document)
* [開発ドキュメントの文章を自動で校正する方法](/posts/how-to-auto-proofread-text-in-document)

## 学び続けるコツ

テクニカルライティングについて学び続ける、つまり技術ブログを続けるコツは、とにかくどんどん書くことです。

「どんどん書く」というのはつまり、文章にこだわりすぎないことです。文章に納得できないと下書きのままになったりしますが、下書きがたまるとモチベーションが下がってしまいます。

こうならないためにも、まず公開することが大切です。公開して、あとからふりかえる。この繰り返しで、文章作成力が身に付いていきます。

私も2013年から技術ブログを書いていますが、つい最近書いた記事でも、もっというとこの記事ですら、書いた後で「もっとよく書けたはず」と思います。

こう思いつつも公開しています。公開して、反省点を次に生かす。これが、テクニカルライティングのスキルを高めるコツだと思います。

## まとめ

テクニカルライティングとは、ある製品について、利用者に分かりやすく伝えることです。そのために必要なスキルには技術力と文章作成力、コミュニケーション力があります。

このうち業務では高まりづらい文章作成力については、技術ブログを書き続けることで身につけることができます。

エンジニアにとって、分かりやすい開発ドキュメントを書くには、テクニカルライティングのスキルが重要になります。私はエンジニアからテクニカルライターになりました。この経験をもとに、テクニカルライティングにはどんなスキルが重要なのか、どう身に付ければよいのかをまとめます。

文章を書くイメージ

エンジニアがテクニカルライティングのスキルを高める方法

開発ドキュメントを書くことになったとき、何から始めればよいか、どう公開まで進めればいいか、よく分からないかもしれません。

私はテクニカルライターで、元々エンジニアだったということもあって、社内向け・社外向けを問わず、開発ドキュメントを書いてきました。

この経験をもとに、開発ドキュメントを書くときの手順を整理してみました。また、それぞれのプロセスについて、関連記事も紹介します。

この記事を読むことで、開発ドキュメントを書くときの全体の流れが分かり、不安なく効率的に公開まで進められたらと思います。

::author

#### 目次

## 開発ドキュメントを公開するまでの基本的な手順

開発ドキュメントを効率的に書くための基本的な手順は、次のような形になります。

| 手順 | 項目 | 概要 |
| --- | --- | --- |
| 1 | 変更要求 | 開発ドキュメントに対する変更要求が作成される |
| 2 | 要件整理 | 変更要求を元に要件を整理する |
| 3 | 企画 | 読者とその悩み、解決策を決める |
| 4 | アウトライン作成 | 文章の構成を決める |
| 5 | 執筆 | 文章を作成・推敲する |
| 6 | レビュー | 関係者に確認してもらう |
| 7 | 公開 | 開発ドキュメントを公開する |

この手順は、開発ドキュメントをどこで公開するのか、あるいは組織のやり方によっても変わると思いますが、基本的にはこのような形だと思います。

なぜこの手順で書くかというと、読者にとってわかりやすく、読みやすい開発ドキュメントを、手戻りを少なく作成できるからです。

例えば、初めから文章を書き始めてしまうと、本来書くべきだったこととは違うことを書いてしまって、修正にたくさんの時間がかかってしまったりします。

そうではなく、書くべきことをしっかりと整理した上で書く、つまり上記の手順に従うことで、効率的に開発ドキュメントを書くことができます。

それでは、それぞれのプロセスについて簡単に説明していきます。

### 1. 変更要求

開発ドキュメントを書くことになったとき、そこには何かしらの変更要求がある、ということになります。

例えば、

* メンバーのために開発環境構築の手順をまとめたい
* APIに機能を追加したので、開発ドキュメントに追加してほしい
* 既存の開発ドキュメントを修正したい

こういった変更要求が、まず発生することになると思います。

この変更要求のときに集める情報をあらかじめ決めておくと、あとで要件を整理するときに、とてもスムーズに行うことができます。

この変更要求のときに集めるべき情報については、「[開発ドキュメントの変更要求のときに集めるべき情報](/posts/how-to-collect-change-requests-for-document)」をご覧ください。

### 2. 要件整理

変更要求が生まれたら、今度はこの変更要求をもとに要件を整理していきます。

具体的には、

* どのページに、何を、いつまでに書くか
* レビュアーは誰か
* 参考となる資料にはどんなものがあるか

といった項目について整理していきます。

仮に「どこに何を書くか」が曖昧な状態で書き始めたとします。この場合、書いたあとで「書く場所が違う」と言われたり、「情報が間違っている」と言われたりすることがあります。

あるいはレビュアーを決めておかないと、開発ドキュメントの公開直前になって、別の人から修正を求められたりすることもあります。こういった問題を防ぐのが、要件整理の目的です。

要件整理について詳しくは、「[開発ドキュメントの要件を整理する方法](/posts/organize-requirements-for-documentation)」をご覧ください。

### 3. 企画

要件を整理したら、次に文章を書く準備をします。つまり企画します。

企画では、読者とその悩み、そして解決策を決めます。なぜなら、開発ドキュメントは「読者の悩みを解決するため」にあるからです。

例えば電子レンジの取扱説明書について考えてみると、電子レンジの利用者が「使い方が分からない」という悩みを解決するために読むと思います。

つまり、取扱説明書は利用者が分かる言葉づかいで書く必要があります。決して、難しい専門用語を使ったりしてはいけません。

この読者と悩み、解決策が曖昧だと、読者にとって分かりづらい文章になってしまいます。

文章を書く前に、まず企画をするところから始めます。開発ドキュメントの企画について詳しくは、「[開発ドキュメントを書く前に決めること](/posts/how-to-plan-document)」をご覧ください。

### 4. アウトライン作成

企画が完了したら、アウトラインで文章の構成を決めます。このアウトラインは、箇条書きで書いていきます。

なぜ文章を書く前にアウトラインを書くかというと、構成を決める段階で修正をしやすいようにするためです。

例えば、最初から文章を書き始めるとします。もし文章の構成が分かりづらければ、文章ごと修正する必要が出てきます。

ただ、文章というものは単に入れ替えればいいという訳ではありません。これは、文章には「文脈」というものがあるためです。

文脈を踏まえた上で、分かりやすく文章を修正するのは、とても大変な作業になります。

このため、アウトラインの段階で話の流れが分かりやすいかどうかを、しっかりと考えます。もし分かりづらくても、箇条書きの段階なので、修正がとても簡単です。

アウトラインの作成について詳しくは、「[開発ドキュメントにおけるアウトラインの書き方](/posts/how-to-write-outline-for-document)」をご覧ください。

### 5. 執筆

アウトラインができたら、実際の文章を書いていきます。このときは、「基本的な書き方」や「表現方法」といったものをふまえた上で書いていきます。

また、文章を書くときは自動校正ツールを導入しておくと、文章の誤りを防ぐことができます。

加えて、文章を書き終えたら、しっかりと推敲をします。これで、分かりやすく読みやすい文章を作ることができます。

文章の書き方について詳しくは、次の3つの記事をご覧ください。

* [開発ドキュメントの書き方](/posts/how-to-write-document)
* [開発ドキュメントの文章における表現方法](/posts/expressions-in-document)
* [開発ドキュメントの文章を自動で校正する方法](/posts/how-to-auto-proofread-text-in-document)

### 6. レビュー

文章を書いたら、他の人にレビューしてもらいます。自分ひとりしかいない場合は難しいですが、他にメンバーがいるときは、レビューをしてもらいます。

なぜなら、情報や文章の誤りが見つかって、より分かりやすく読みやすい文章になるからです。

例えば情報に誤りがあると、読み手の時間を余計に奪ってしまうことになります。企業として開発ドキュメントを公開している場合は、信頼性の問題にもなり得ます。

このため、開発ドキュメントを公開する前に、しっかりとレビューをしてもらいます。レビューについて詳しくは、「[開発ドキュメントをレビューする方法](/posts/how-to-review-document)」をご覧ください。

### 7. 公開

文章を書いてレビューを通過したら、いよいよ開発ドキュメントを公開します。

公開するにあたって気をつけることはそんなにないですが、いくつかやった方がよいことがあります。

公開するときに気をつけることを押さえておくことで、より多くの人に読んでもらったり、公開に対するリスクを減らすことができます。

開発ドキュメントの公開について詳しくは、「[開発ドキュメントを公開したときにやること](/posts/what-to-do-when-publish-document)」をご覧ください。

## まとめ

開発ドキュメントを変更する内容が決まってから、公開するまでの基本的な流れを紹介しました。

この記事で全体の流れを把握しつつ、各プロセスについて作業するときは関連記事を読むことで、開発ドキュメントを効率的に書けるようになればと思います。

開発ドキュメントを書くことになったとき、何から始めればよいか、どう公開まで進めればいいか、よく分からないかもしれません。この記事を読むことで、開発ドキュメントを書くときの全体の流れが分かり、不安なく効率的に公開まで進められたらと思います。

手順のイメージ

開発ドキュメントを公開するまでの基本的な7つの手順

開発ドキュメントを書き終わったら、他の人に読んでもらうよう公開すると思います。このとき何をすればいいのか、何に気をつければいいのかが分からないかもしれません。

公開するにあたって、やるべきことは多くないのですが、気をつけること、やった方がいいことはいくつかあります。

私はテクニカライターとして開発ドキュメントを書いています。また、元々はエンジニアとして、社内向けの開発ドキュメントを書いていました。

この記事に書いてあることは基本的なことですが、実践することによって、より多くの人に読んでもらえるようになったり、公開に伴うリスクを減らすことができると思います。

::author

#### 目次

## 開発ドキュメントを公開するときにやること

開発ドキュメントを書き終えて、レビューなどを通してページが完成したとします。あとは公開するだけですが、公開にあたってやることは多くありません。

開発ドキュメントを公開したときは、次の3つを行います。

1. 正常に公開されたことを確認する
1. 公開したことを共有する
1. チケットのステータスを変更する

それぞれについて、簡単に見ていきます。

### 1. 正常に公開されたことを確認する

まずは何よりも、ページが正しく表示されていることを確認します。このとき余裕があれば、誤字・脱字がないかを軽くチェックするといいと思います。

注意すべき点として、社内のドキュメント共有サービスを利用している場合は、ユーザーごとにアクセス制限がかかっている可能性があります。この場合は、見てほしいユーザーに対して適切な権限があるかどうかを確認します。

### 2. 公開したことを共有する

ページが問題なく表示できることを確認したら、次はページを読んでほしい人や、「開発ドキュメントを書いてほしい」と依頼してきた人などに共有します。

これにより、よりたくさんの人に開発ドキュメントを読んでもらうことができます。TwitterなどのSNSアカウントを運用している場合は、SNS上でも共有します。

このとき、ページを公開するにあたってレビュー等に協力してくれた人には、感謝を伝えるとよいと思います。

### 3. チケットのステータスを変更する

あとは、開発ドキュメントを変更するために作成されたチケットのステータスを「完了」に変更します。

記事の執筆は、GitHub Issueのようなチケットで管理していることがあると思います。この場合は、チケットのステータスを完了にします。

このとき、公開したページのURLといった情報を記録しておくと、後日確認するときなどの参考になります。

## まとめ

開発ドキュメントを書き終えて公開するときは、ページが正しく表示されるかを確認して、関連する人に共有し、最後にチケットのステータスを変更します。

これにより、多くの人に記事を読んでもらえたり、公開に伴うリスクを減らすことができます。

開発ドキュメントを書き終わったら、他の人に読んでもらうよう公開すると思います。公開するにあたって、やるべきことは多くないのですが、気をつけること、やった方がいいことはいくつかあります。この記事を読むことで、より多くの人に読んでもらえるようになったり、公開に伴うリスクを減らすことができると思います。

記事を公開するイメージ

開発ドキュメントを公開したときにやる3つのこと

開発ドキュメントを書くことになったとき、何を書けばよいかが分からない、ということはないでしょうか。

この問題は、開発ドキュメントを書くために必要な情報が揃っていない場合に起こりがちです。

私はテクニカルライターとして、開発ドキュメントを書いています。「どうすれば効率的に開発ドキュメントを書いていけるか」を考える中で、最初に必要な情報を集めること、つまり変更要求の方法が重要だと感じました。

この記事を読むことで、開発ドキュメントを書く上で必要な情報が集まり、効率的に書けるようになればと思います。

::author

#### 目次

## 変更要求とは何か

この記事でいう変更要求とは、「開発ドキュメントに対して変更したい内容を記入したもの」をいいます。

開発ドキュメントを書くことになったとき、そこには何かしらの変更要求があります。例えば、

- メンバーのために開発環境を構築する手順をまとめたい
- APIに機能を追加したので、開発ドキュメントに追記してほしい
- 既存の開発ドキュメントに誤りがあるので修正したい

こういった変更要求が、最初に発生することになります。

変更要求を上げる人（=要求者）は、あなたや他のメンバー、あるいは外部に公開している開発ドキュメントの場合は、その製品の利用者かもしれません。

このように、開発ドキュメントに対して変更したい内容を記入したものが変更要求です。なお、この変更要求は、GitHubのIssueのようなチケットで管理されたりします。

## なぜ変更要求のときに情報を集めるのか

変更要求のときは、要求者から「変更したい内容に関する情報」をもらうことが重要です。なぜなら、情報がないと要件の整理が非効率になるからです。

例えば、「開発ドキュメントにこういう誤りがあるので修正してほしい」という依頼を受けたとします。このとき、

- どのページのどの部分なのか
- いつまでに修正するべきか
- 修正内容は誰にレビューしてもらえばいいか

などが分からないときがあります。この場合、要件を整理するのに必要以上に時間がかかってしまいます。

また、情報が曖昧なまま開発ドキュメントを修正してしまうと、そもそもの意図を履き違えた変更になってしまうかもしれません。

こういった問題を防ぐためにも、あらかじめ変更に関する情報を集めることが重要になります。

## 変更要求のときに集める情報

開発ドキュメントに新しいページを追加したり、既存の部分を変更するとき、あらかじめ要求者から次の情報を集めておきます。

| 順番 | 項目 | 概要 |
| --- | --- | --- |
| 1 | 概要 | 変更の概要が分かるよう簡潔にまとめる |
| 2 | 関連する資料 | 変更に関連するWikiや外部ページのURLなど |
| 3 | 関係者 | レビュアーや、疑問に対する質問相手など |
| 4 | スケジュール | いつ公開したいか、あるいはいつまでに公開しておきたいか |
| 5 | 変更の詳細 | 変更するページ、重要度、またどう変更するか |
| 6 | 備考 | 変更に関して、その他に伝えておきたいこと |

例えば、あなたが「こういう開発ドキュメントを書いてほしい」という依頼をされたら、まず関連する資料やレビュアー、スケジュールといった情報を要求者から集めます。

これらの情報があれば、「この変更要求に対応する・しない」の判断がしやすくなります。また、実際に対応するときに必要な情報があるので、すぐに次の作業に着手できます。

### 変更の詳細における重要度

この中の「変更の詳細」について、重要度は次のように設定するとよいです。これにより、リソース状況に応じて対応するかどうかの判断がしやすくなります。

| 順番 | 重要度 | 概要 |
| --- | --- | --- |
| 1 | Must | 必ず対応してほしい |
| 2 | Nice to have | できれば対応してほしい |

## 変更要求の手順をまとめたページを公開する

変更要求のときに集める情報が分かったとして、では実際にどう変更要求を記入してもらえばよいのでしょうか。これは、変更要求の手順をまとめたページを作成して、公開しておくとよいです。

要求者は、このページの内容にしたがって変更要求を出すことになります。

このページの目的は、要求者に「変更要求のときに集める情報」で示した情報を記入してもらうようことです。こうすることで、質の高い変更要求が来るようになり、要件の整理が効率的に行え、結果としてよりよい開発ドキュメントにつながります。

![GitHubのIssueテンプレートの例](//images.ctfassets.net/pppgbgujcovf/6datzxTGbJezQpZozwqHJu/240657002a1e7d22f77e9f4497c887ed/github-issute-template.png)
:img-caption{text="GitHubの変更要求の例"}

また、例えば変更要求をチケットで管理している場合、変更要求用のテンプレートを作っておくのも効果的です。これは[GitHubのIssueテンプレート](https://github.com/github/docs/issues/new/choose)がイメージしやすいかもしれません。

まずは変更要求の手順をまとめたページを作成してみましょう。

## ページ作成時に気をつけること

変更要求のときに集める情報をいくつか紹介しましたが、これらの項目はすべての要求者に対して記入を必須にするべきではありません。

要求者によっては、分からない項目があったりします。この場合は「無理に記入しなくてもよい」ということを伝えておく必要があります。

なぜなら、変更要求を書いてもらう目的は、できるだけ要件整理を効率的に行うことだからです。つまり、分からないことを求めても意味がありません。

変更要求を出すのが難しいと、逆に変更要求が来なくなる危険性もあります。

例えば一般の利用者によるバグの報告について考えてみます。バグの報告については、バグの内容や再現条件が分かればよく、レビュアーやスケジュールについては関与できないと思います。

こういった「書くことが難しい項目」まで要求してしまうと、貴重なバグ報告がなくなるかもしれません。

要求方法をまとめたページを作るときは、すべての人にすべての項目を必須にしないようにする必要があります。

## まとめ

変更要求とは、開発ドキュメントに対して変更したい内容を記入したものです。あらかじめ必要な情報を集めておくことによって、効率的に開発ドキュメントが書けるようになります。

注意点として、変更要求を出す人によっては記入しなくてもよいようにするなど、変更要求の手順を調整する必要があります。

効率的に開発ドキュメントを書くには、最初に必要な情報を集めること、つまり変更要求の方法が重要です。この記事を読むことで、開発ドキュメントを書く上で必要な情報が集まり、効率的に書けるようになればと思います。

集めるイメージ

開発ドキュメントの変更要求のときに集めるべき6つの情報

私はエンジニアからテクニカルライターに転向しました。

エンジニアとテクニカルライターでは、もちろん必要なスキルが違います。テクニカルライターになった今、改めて「テクニカルライターにとって重要なスキル」を整理してみました。

エンジニアとして開発ドキュメントを書くには、あるいはテクニカルライターとして成長するには、どんなスキルがあるとよいのか。この記事が参考になれば嬉しいです。

::author

#### 目次

## テクニカルライターにとって重要なスキル

テクニカルライターには、次の3つのスキルが重要になります。

1. 技術力
2. 文章作成力
3. コミュニケーション力

この根拠について、次に説明していきます。

### テクニカルライターとは

この記事でいうテクニカルライターとは、テクニカルライティングを主な業務とする職種です。テクニカルライティングとは、ひとことでいうと、

> ある製品について、利用者にわかりやすく伝えること

です。テクニカルライティングについて詳しくは、「[テクニカルライティングとは何か](/posts/what-is-technical-writing)」をご覧ください。

### 3つのスキルが重要な理由

この定義からいくと、「ある製品に関する知識」、つまり技術力が重要です。また、わかりやすく伝えるための文章作成力。この2つが重要だといえます。

ここでいう技術力とは、「技術に関する一般的な素養」のことをいいます。例えばAPIを公開している製品の場合は、APIリクエストを実行するための技術などがあります。他にも、製品に関するドメイン知識も重要です。

まとめると、技術の素養がありつつ、製品にも詳しい状態が理想的だといえます。

また、コミュニケーション力も重要です。開発ドキュメントを書くにあたっては、他の開発者や製品担当者など、いろんな方とコミニケーションを取ることになります。

技術力とコミニケーション力、これに加えて文章作成力を身に付けていることが、よりよいテクニカルライターだといえます。

## スキルが不足しているとどうなるか

例えば技術力がないと、開発ドキュメントの内容が不正確なものになったり、開発ドキュメントを作成するのに時間がかかってしまいます。

また文章作成力がないと、読者にとって読みづらく、分かりづらい開発ドキュメントになってしまいます。

コミニケーション力がない場合は、開発ドキュメントの要件をうまく整理できなかったり、たくさんの時間を使った結果として不正確な開発ドキュメントが仕上がってしまいます。

技術力と文章作成力、コミニケーション力は、どれが欠けてもテクニカルライターとしての業務に影響が出てしまいます。この3つのスキルを身に付ける努力が必要だといえます。

:::note
### コミュニケーションが苦手な場合

私は、テクニカルライターになる前はエンジニアやプロダクトマネージャーをしていましたが、コミニケーションが苦手でした。今でもテクニカルライターとして苦労している部分があります。

ただ、口頭でのコミニケーションは苦手ですが、Slackなどテキストベースでのコミュニケーションは得意です。自分の中でバランスをとりながら仕事をしています。
:::

## スキルの身につけ方

この3つのスキルは、どうやって身に付ければよいのでしょうか。ひとつの考え方を紹介します。

### エンジニアの場合

エンジニアの方は、文章作成の練習をします。

エンジニアなら、ふだんの業務の中で、技術力とコミニケーション力は自然に身に付くと思います。設計をしたりコードを書いたりすることで、技術力が身に付きます。

また、開発の過程で他のエンジニアやデザイナー、プロダクトマネージャーの方とコミュニケーションをとると思います。

一方で、業務の中で文章を書くことはあまり多くないと思います。加えて、文章作成力を身に付けるには、ただ書くのではなく、ある程度の方法論を学んだ上で量をこなす必要があります。

方法論については、「[開発ドキュメントの書き方](/posts/how-to-write-document)」をご覧ください。また書く場所については、技術ブログがいいと思います。こちらについては「[技術ブログ入門](/guides/tech-blog)」が参考になります。

### テクニカルライターの場合

テクニカルライターの方は、技術力を身に付けます。

ふだんの業務の中で、文章作成力とコミニケーション力については身に付いていくと思います。これに加えて、技術力を身に付ける努力をします。

技術力を身に付ける方法のひとつとして、例えば個人開発があります。具体的には、ウェブサービスやライブラリをつくってみます。

技術力を身に付ける努力をしつつ、ふだんの業務で文章作成力やコミニケーション力を高めることで、よりよいテクニカルライターになれると思います。

## その他のスキル

テクニカルライターにとって重要なその他のスキルとして、英語があります。英語は、もちろん英語のドキュメントを書く場合にはとても重要になります。

特に、開発ドキュメントについては英語で書くことがルール化されている会社も多いと思います。他にも、RFCなど一次情報が英語の場合もあります。

ただ、英語をネイティブレベルで読み書きできる必要はないと思います。例えばDeepLのような翻訳ツールを使いつつ、基本的な読み書きができるレベルの英語力があればよさそうです。

ということで、必要に応じて英語も身につけた方がよいです。ただ、英語はテーマが広すぎるので、「英語を一旦捨てる」と割り切るのも、テクニカルライターの生存戦略としてはありだと思います。

## おわりに

テクニカルライターにとって重要なスキルとして、技術力と文章作成力、コミニケーション力の3つを紹介しました。

ふだんの業務に加えて、不足しているスキルを身に付けることで、よりテクニカルライターとして成長できると思います。

エンジニアとテクニカルライターでは、必要なスキルが違います。テクニカルライターになった今、改めて「テクニカルライターにとって重要なスキル」を整理してみました。エンジニアとして開発ドキュメントを書くには、あるいはテクニカルライターとして成長するには、どんなスキルがあるとよいのか。この記事が参考になれば嬉しいです。

スキルのイメージ

テクニカルライターにとって重要な3つのスキル

私はテクニカルライターとして、開発ドキュメントを書いています。また元エンジニアで、エンジニアとしても開発ドキュメントを書いたり、レビューをしていました。

この記事では、開発ドキュメントのレビューをする方法や、レビューを依頼するときに私が気をつけていることをまとめています。

エンジニアやテクニカルライターの方にとって、開発ドキュメントをレビューするときの参考になればと思います。

::author

#### 目次

## 開発ドキュメントにおけるレビューとは

開発ドキュメントに限らないことですが、文章におけるレビューとは、「文章の作成者とは別の人=レビュアーが、文章や情報の誤りについて指摘することで、よりよい文章にするためのプロセス」のことをいいます。

やることは、次の3つになります。

| 優先度 | プロセス | 内容 |
| --- | --- | --- |
| 1 | 校閲 | 情報の誤りを直す |
| 2 | 校正 | 文字の誤りを直す |
| 3 | 推敲 | 文章を練り直す |

レビューでやることについて、優先度をもとに見てみます。

### レビューにおける優先度

レビューにおける優先度は「校閲 > 校正 > 推敲」の順番になります。

まず、文章の情報に誤りがある場合は、そもそも文章を公開すべきではありません。第一に、情報の正しさを確認する必要があります。

次に文字の正しさを確認します。誤字・脱字などがないか、です。校正は目視でも行いますが、どうしても確認漏れが出てきてしまいます。

これを防ぐために、自動校正を取り入れると、確実かつ効率的に校正を行うことができます。自動校正については、「[開発ドキュメントの文章を自動で校正する方法【textlint】](/posts/how-to-auto-proofread-text-in-document)」をご覧ください。

最後に推敲です。推敲は、文章をより読みやすく、わかりやすくするためのプロセスになります。例えば文章の構成を変えたり、内容を追加したりします。推敲については、「[開発ドキュメントの文章を推敲する方法](/posts/how-to-improve-document)」をご覧ください。

## 文章をよくする以外の目的

レビューの主な目的については、説明した通りです。ただ、レビューには、文章をよりよくする以外にも重要な役割があります。それは、

- 変更に対する影響範囲の確認
- メンバーの教育

の2つです。

### 変更に対する影響範囲の確認

まずひとつ目に、レビューでは開発ドキュメントに対する変更の範囲が適切かどうかを確認します。変更によって、開発ドキュメントの既存のページを修正する必要はないか。このようなことを考える必要もあります。

文章以外にも、変更によって関係者との調整が必要ではないか。例えば新しく登場した用語について、開発ドキュメント上で使用してもよいかどうかを広報に確認したり、利用規約等については法務に確認したり、といったことが必要になります。

こういったことは、もちろん開発ドキュメントの変更に対する要件ができた段階でも確認しますが、レビューのプロセスでも確認しておくとよいです。

### メンバーの教育

レビューのもうひとつの目的は、メンバーの教育です。レビューはよりよい文章にするプロセスです。このため、レビューをしたり、レビューを受けること自体が、テクニカルライティングに関する学びの場となります。

これが、よりよい文章を書けるきっかけになります。また、レビューの内容をチーム内で共有すれば、チーム共通の財産にもなります。

## レビュー時の観点

ここでは、開発ドキュメントのレビューにおいて、どこを見るのか、どうコメントするかのふたつを見ていきます。まずはレビュー時の観点についてです。

開発ドキュメントをレビューするときは、前述した通り、校閲・校正・推敲、これに加えて影響範囲について確認していきます。

### 校閲

校閲では、情報の誤りを見つけて直します。特に、次のような情報が出てきたら、その根拠となる資料等を確認します。

- 固有名詞：メソッド名など
- 数字：日付や値など

またソースコードがある場合は、動作環境をもとに検証します。校閲については、情報に詳しいプロダクトマネージャーや開発者がいれば、その方にレビューを依頼するのも重要です。

### 校正

校正では、文字の誤りを見つけて直します。例えば、次のようなものがないか確認します。

- 誤字・脱字
- 表記のばらつき：ウェブとWebなど
- 閉じひらきの誤り
- ですます調・である調の混用

校正については、目視で行うこともできますが、自動校正を活用すると効率よく校正を行うことができます。自動校正については、「[開発ドキュメントの文章を自動で校正する方法【textlint】](/posts/how-to-auto-proofread-text-in-document)」をご覧ください。

### 推敲

推敲では、文章を練り直します。つまり、より読みやすい、わかりやすい文章にするためのコメントをします。

具体的には、次のような項目を確認します。

1. 一文を短く切る
2. 結論を先に述べる
3. 指示語を使わない
4. 主語を明確にする、述語との距離を近づける
5. ひらく・閉じるを統一する
6. 再現条件を示す
7. 前提を揃える
8. 見出しや箇条書き、表などを適切に用いる
9. 読者に伝わる用語を使う

この項目は、「[開発ドキュメントの書き方。意識したい9つのこと【技術編】](/posts/how-to-write-document)」より引用しています。あわせてご覧ください。

### 影響範囲

文章に直接関係することではないですが、レビューにおいては影響範囲を確認することも重要です。

開発ドキュメントの変更に関連して、別のページを修正する必要はないか。あるいは、法務面の確認や、セキュリティチェックを実施する必要がないか、なども確認します。

特に後者は、ややテクニカルライティングの業務とは離れている気もしますが、こういったところもケアできることが重要だと思っています。

## コメントの書き方

レビュー中に、修正点や改善した方がよいところを見つけたら、コメントをします。このとき、次のふたつのことに気をつけます。

- 作成者が対応しやすいようにする
- 感情面に配慮する

### 作成者が対応しやすいようにする

作成者が、レビューをもらったときに対応しやすいようにするには、コメントに重要度を添えます。

レビュー中のよくある問題として、コメントをもらったのはいいものの、「どう対応すればいいかわからない」ということがあります。こういった問題を防ぐために、コメントに重要度を添えます。

重要度には、代表的なものとして次の3つがあります。

| 重要度 | 内容 |
| --- | --- |
| Must | 必ず対応すべき |
| Nice to have | 可能であれば対応した方がよい |
| Nits | 対応しなくても問題ない |

このとき、できるだけMustかNice to haveのものをコメントするように心がけます。なぜなら、Nits=Nitpicking（細かい指摘）は対応した方がよいかが分かりづらいためです。

また、コメントをするときは、重要度の根拠を示すことも大切です。「なぜMustなのか」ということが分かると、作成者もそのコメントの内容に対応しやすくなります。

他のよくある例として、IMO = In my opinion（私の意見としては）というものもあります。ただこれはNitsよりもさらに対応すべきかどうかが分からないので、避けた方が無難だと思います。

個人的には、対応してもしなくてもどちらでもよいことはあまりコメントしないようにしています。その方がレビューがスムーズに進みますし、作成者の気持ちにも配慮できるためです。

### 感情面に配慮する

レビューにおけるコメントは、場合によってはネガティブに受け取られる可能性があります。これは仕方のないことですが、次のことに気をつけることで、ポジティブなレビューに近づけることができます。

- 表現を柔らかくする
- 絵文字を用いる
- 客観的な根拠を示す
- よいところもコメントする
- 口頭での確認も活用する

これに限らず、大切なのは「相手を気づかう」ということだと思います。普段のコミニケーションと同じように相手に配慮することで、よりよいレビューになると思います。

また、口頭でレビューの内容を確認することも重要ですが、その際は口頭で話した内容をコメントとしてメモします。こうすることで記録として残りますし、他のメンバーが会話の内容を参照することもできます。

## レビューを依頼する方法

レビューは、依頼するときにも気をつけることがあります。これは、レビュアーに効率よくレビューをしてもらうために必要になります。

まず、レビューをお願いする前に、しっかりと推敲をする必要があります。これについては、「[開発ドキュメントの文章を推敲する方法](/posts/how-to-improve-document)」をご覧ください。

その上で、開発ドキュメントの要件を整理して提示します。具体的には、レビューを依頼するときに次のことを書きます。

- 変更の概要
- 関連情報：Wikiなど
- 公開予定日
- 関係者：企画、開発担当者など
- スコープ：今回の対応範囲

開発ドキュメントの要件については、「[開発ドキュメントの要件を整理する方法](/posts/organize-requirements-for-documentation)」をご覧ください。

あとは、特に見てほしいポイントや、困っていることがあれば書いておくとよいです。

## おわりに

レビューは、開発ドキュメントをよりよいものにするために必要なプロセスになります。

レビューをする側も、依頼する側も気をつけることで、効率的かつ効果的なレビューを行うことができます。

この記事では、開発ドキュメントのレビューをする方法や、レビューを依頼するときに私が気をつけていることをまとめています。エンジニアやテクニカルライターの方にとって、開発ドキュメントをレビューするときの参考になればと思います。

レビューのイメージ

開発ドキュメントをレビューする方法

私はテクニカルライターとして働いていて、仕事では開発ドキュメントを、プライベートでは技術ブログを書いています。

文章を書いたら、基本的には公開する前に推敲をしています。ただ、推敲のやり方を自分の中で言語化できていませんでした。

この記事では、自分なりの推敲のやり方をまとめています。より読みやすい、分かりやすい文章にするきっかけになれば嬉しいです。

::author

#### 目次

## 推敲とは何か

推敲とは、[Wikipedia](https://ja.wikipedia.org/wiki/推敲)によると、

> 推敲（すいこう）とは、文章を何度も練り直すこと。

とあります。開発ドキュメントにおいては、「よりよい開発ドキュメントにするために、文章を何度も練り直すこと」だといえます。

例えば、文章の構成や表現方法を変えることが推敲にあたります。

### 校正・校閲との違い

推敲の他に、「校正」と「校閲」という言葉があります。この三つを比較すると、次のようになります。

| 種類 | 目的 | 効果 |
| --- | --- | --- |
| 校正 | 文字の間違いを直す | マイナスを減らす |
| 校閲 | 情報の間違いを直す | マイナスを減らす |
| 推敲 | 文章を練り直す | プラスを増やす |

この表のように、校正と校閲が間違いを直す、つまりマイナスを減らすのに対して、推敲はプラスを増やす作業になります。

校正、校閲は、一般的には推敲の後に行われるようです。これは、先に校正、校閲をしたとしても、推敲によって文章が変わった場合に再度校正、校閲の作業が発生するためだと思います。

推敲で文字や情報の間違いを直すことももちろんできますが、それよりも推敲ではプラスを増やすことに集中すべきだといえます。

## なぜ推敲が必要か

推敲は、より読みやすい、分かりやすい開発ドキュメントにするために必要な作業になります。

文章を書いているときは、書いている部分に集中すると思います。つまり、なかなか全体を俯瞰することができません。

例えば、あるところは詳しく書いているけど、あるところは説明が足りない、といった問題がありします。このときは、構成を変えたり、文章ではなく表や図で説明した方がよいかもしれません。

このように、推敲をしないと見えてこない改善案があります。よりよい開発ドキュメントにするためにも、推敲が必要になります。

## 推敲のやり方

それでは、推敲のやり方について見ていきます。ただ、推敲といってもいろんな方法があるようです。

いろいろ試してみて、自分の中では次のやり方が効果的でした。

1. しばらく寝かせる
2. 読者になりきる
3. 音読する

ひとつずつ説明します。

### 1. しばらく寝かせる

文章を書き終えたら、いきなり推敲を始めるのではなく、しばらく寝かせます。これは、自分とは別の視点で、客観的に文章を読むために必要なプロセスになります。

可能であれば一晩、急いでいるときでも一時間くらいは、推敲までに時間を空けたいところです。

### 2. 読者になりきる

文章は、もちろん読者が読みます。文章が想定している読者については、文章を書く前の企画段階で決めていると思います。この読者になりきります。

企画について詳しくは、「[開発ドキュメントを書く前に決めるべき3つのこと【企画編】](/posts/how-to-plan-document)」をご覧ください。

### 3. 音読する

文章をしばらく寝かせて、読者になりきったら、次は文章を音読します。つまり、声に出して読みます。

音読をすることで、目で読むときより「読みやすさ」が分かります。例えば、スラスラと読めなかったり、読んでいて理解できないことがあったりします。

音読をする上で改善点が見つかったら、補足したり、構成を変えたりします。

## 推敲力を上げる練習

推敲に限らないですが、どんなスキルでも、繰り返し行うことで身についていくと思います。

この推敲力を上げるための練習について、技術ブログを書くことがよいと考えています。推敲に限らず、テクニカルライティング全般について学べます。

技術ブログについて詳しくは、「[技術ブログ入門](/guides/tech-blog)」をご覧ください。

## おわりに

推敲をすることで、読みやすさ、分かりやすさが大きく向上します。文章を書いたら、必ず推敲をしたいところです。

あなたがやっている推敲のやり方があれば、ぜひ[@zenizh](https://twitter.com/zenizh)までご連絡ください。

私は文章を書いたら、基本的には公開する前に推敲をしています。ただ、推敲のやり方を自分の中で言語化できていませんでした。この記事では、自分なりの推敲のやり方をまとめています。より読みやすい、分かりやすい文章にするきっかけになれば嬉しいです。

文章を改善するイメージ

開発ドキュメントの文章を推敲する方法

私はテクニカルライターとして、開発ドキュメントを書いています。読みやすい、分かりやすい文章を書くときは、

- 一文を短く切る
- 結論を先に述べる

など、必ず意識することがあります。

以前は満足のいく文章を書けませんでしたが、文章を書く中で学び、「これを意識すればよい文章が書ける」という自分なりのルールを見つけました。

このような内容はいろんなところで言われているので、特に真新しい内容はないかもしれませんが、よりよい文章を書くきっかけになればうれしいです。

::author

#### 目次

## 文章を書く前にやること

よい文章を書くには、実際に文章を書く前に、読者は誰か、どういう悩みを解決するのかを企画することが大切です。また、それを元にアウトラインを書いておきます。

このふたつを元に文章を書くことで、読みやすい開発ドキュメントにつながります。これについては、次の記事をご覧ください。

- [開発ドキュメントを書く前に決めるべき3つのこと【企画編】](/posts/how-to-plan-document)
- [開発ドキュメントにおけるアウトラインの書き方](/posts/how-to-write-outline-for-document)

## 開発ドキュメントの書き方

企画とアウトラインの作成が終わったら、実際に文章を書いていきます。

文章を書くときは、次の9つを意識して書きます。これだけで、読みやすさ、分かりやすさが大きく向上します。

1. 一文を短く切る
1. 結論を先に述べる
1. 指示語を使わない
1. 主語を明確にする、述語との距離を近づける
1. ひらく・閉じるを統一する
1. 再現条件を示す
1. 前提を揃える
1. 見出しや箇条書き、表などを適切に用いる
1. 読者に伝わる用語を使う

ひとつずつ説明します。

### 1. 一文を短く切る

一文とは、句点で区切られた文字列のことをいいます。この一文を短く切ります。

一文が長いと、文章を読んでいるときに、頭の中に情報が積み重なっていきます。結果として、文章の理解が追いつかなくなります。

どうすればよいかというと、例えば「〜で」や「〜が」のようなつなぎ言葉が出てきたときに、そこで区切ります。

こうすることで、一文が短くなり、読みやすい文章につながります。

### 2. 結論を先に述べる

文章を書くときは、まず結論を先に書きます。はじめに結論がないと、「結局何がいいたいんだろう」と、読む人がモヤモヤしてしまいます。

背景や例などを書いてしまいがちですが、まずは結論を先に書くことを意識します。

### 3. 指示語を使わない

指示語とは「それ」や「これ」のようなものですが、できる限りこの指示語を使わないようにします。

文章の中で指示語が出てくると、「それって何だっけ？」となり、前の文章に戻ってしまいます。「それ」が分かったとしても、今度は「どこまで読んだっけ？」という問題も生まれます。

指示語を使わなければ、文章を読む上で前に戻ったりする必要がありません。

「指示語を一切使わない」というのは難しいかもしれませんが、適切に用いることで、読みやすい、分かりやすい文章につながります。

### 4. 主語を明確にする、述語との距離を近づける

文章を書いていると、つい主語を省略してしまうことがあります。例えば、

> 分かりやすい開発ドキュメントを書くことを目的とした講義を先日受講した

という文章があったとします。この主語は「私」かもしれませんし、別の誰かかもしれません。

また、この文章における述語は「受講した」になりますが、主語との距離が離れているため、「受講した」のは誰かが分かりづらいです。

これを防ぐには、次のような文章にします。

> 私は先日ある講義を受講しました。この講義は分かりやすい開発ドキュメントを書くことを目的としたものでした

文章は長くなりましたが、主語が明確で、述語との距離も近いため、読みやすく感じると思います。

主語を明確にし、述語との距離を近づけることで、読者の誤解を減らすことができます。開発ドキュメントでは特に気をつけたい項目です。

### 5. ひらく・閉じるを統一する

「ひらく」とはひらがなで書くことで、「閉じる」とは漢字で書くことをいいます。例えば、

| ひらく | 閉じる |
| --- | --- |
| はじめに | 初めに |
| とき | 時 |
| たとえば | 例えば |
| ください | 下さい |
| すべて | 全て |

のようになります。このひらく・閉じるに決まったルールはありませんが、同じ言葉に関しては、開発ドキュメントで統一します。

具体的には、同じ開発ドキュメント内では、同じ意味で「はじめに」と「初めに」を混用しない、ということになります。

ちなみに、漢字が多いと固く、ひらがなが多いとやわらかい印象を読者に与えます。ひらがなが多すぎると、稚拙な印象を与えてしまいます。

参考までに、[日経クロステックの記事](https://xtech.nikkei.com/it/article/COLUMN/20110715/362494/)では、「漢字3割、ひらがな7割」が読みやすいとしています。

:::info
### ひらく・閉じるのルール

テクニカルライティングの現場では、「[記者ハンドブック 第14版: 新聞用字用語集](//af.moshimo.com/af/c/click?a_id=2464392&amp;p_id=170&amp;pc_id=185&amp;pl_id=4062&amp;url=https%3A%2F%2Fwww.amazon.co.jp%2Fdp%2F4764107333)」をひらく・閉じるの根拠にしているところが多いようです。
:::

### 6. 再現条件を示す

再現条件とは、ライブラリやフレームワークのバージョン情報などをいいます。この再現条件を記事の中で示す必要があります。

バージョンが変わると、ソフトウェアの動作が変わる可能性があります。どの動作環境で検証したのか、記事の内容においては正しく動作するようにしておくことが重要です。

### 7. 前提を揃える

読む人のバックグラウンドによって、文章の読み取り方が変わる可能性があります。

例えば「[テクニカルライティング](/posts/what-is-technical-writing)」という用語について、ウェブの文脈であれば開発ドキュメントが連想されますが、家電製品の場合は取扱説明書になります。

その記事が前提としている用語について、読み手によらず認識を揃えるために、前提を揃えることが読みやすさにつながります。

### 8. 見出しや箇条書き、表などを適切に用いる

文章だけだと読みづらい、分かりづらい場合があります。このようなときは、見出しや箇条書きなど、文章以外の表現方法で情報を伝えます。

箇条書きのような表現方法について詳しくは、「[開発ドキュメントの文章における表現方法【箇条書き・表など】](/posts/expressions-in-document)」をご覧ください。

### 9. 読者に伝わる用語を使う

開発ドキュメントはいろんな人が読むと思います。その製品に詳しい人もいれば、初学者もいるでしょう。

読む人によって、伝わる用語は変わってきます。つまり、読み手に合わせて使う用語を選ぶ必要が出てきます。

「文章を書く前にやること」でも書きましたが、文章を書く前に読者を決め、この読者に合わせて文章を書くことを意識します。

## 書き方を身につけるには

以上の9つを意識して文章を書くことで、読みやすい、分かりやすい文章につながります。では、この技術をどうやって身につければよいのでしょうか。

もちろん業務で開発ドキュメントを書く際に意識することで、少しずつ身についていくと思います。

開発ドキュメントを書く頻度が高くない場合は、ブログや個人出版、あるいはTwitterなどで実践するとよいと思います。

私は技術ブログを書いているということもあり、ブログがもっともよい方法だと考えています。私はテクニカルライターになるための文章力を、ブログを通して身につけました。

技術ブログについて詳しくは、「[技術ブログ入門](/guides/tech-blog)」をご覧ください。

## おわりに

読みやすい、分かりやすい開発ドキュメントを書くための9つのことを説明しました。文章を書くときは、この技術を意識することで、よりよい文章につながります。

<div class="tracking-tags">
  <img src="//i.moshimo.com/af/i/impression?a_id=2464392&amp;p_id=170&amp;pc_id=185&amp;pl_id=4062" alt="" width="1" height="1" style="border: 0px;" />
</div>

読みやすい、分かりやすい文章を書くときは、「一文を短く切る」「結論を先に述べる」など、必ず意識することがあります。文章を書く中で学び、「これを意識すればよい文章が書ける」という自分なりのルールを見つけました。この記事を読むことで、よりよい文章を書くきっかけになればうれしいです。

講義のイメージ

開発ドキュメントの書き方。意識したい9つのこと【技術編】

私はテクニカルライターとして開発ドキュメントを書いています。

文章を書いているのですが、文章だけだと分かりづらかったり、読みづらい文章になってしまいます。

分かりやすい文章を、それも早く書くには、箇条書きや表のような「表現方法」を押さえておくことがポイントだと考えています。

この記事では、文章における表現方法についてまとめます。

::author

#### 目次

## 文章における表現方法とは

この記事でいう表現方法とは、文章をどう表現するか、その種類のことをいいます。例えば箇条書きや表などがあります。

世の中の開発ドキュメントにはどんな表現方法が使われているかは、実際の開発ドキュメントを見てみるのが早いです。これについては「[開発ドキュメントを書くときの参考になるサイト](/posts/reference-sites-for-documentation)」をご覧ください。

この記事では、上記参考サイトの中でも使われている表現方法をもとに整理しています。

## なぜ表現方法を知っておく必要があるのか

よい文章を、早く書くには、書くための道具を準備しておくことが大切だと考えています。

文章の表現方法は、料理における菜箸やおたまのようなものだと思います。つまり、品質の高いものを、早く作るための道具になります。

文章においては、どんな表現方法があるのかを押さえておくことが大切です。

## 基本的な表現方法

まず、基本となる表現方法を5つ説明します。これらはどんな開発ドキュメントでも使いやすく、分かりやすさが大きく向上します。

| 番号 | 表現方法 | 概要 |
| :---: | --- | --- |
| 1 | 箇条書き | 順序のある、またはない情報の要点を簡潔に伝える |
| 2 | 表 | いくつかの項目を元に情報を整理する |
| 3 | ソースコード | 実際の実装例やコマンドを提示する |
| 4 | 図 | 概念図やシーケンス図を用いて、視覚的に情報を伝える |
| 5 | メッセージ | 補足や注意事項などを視覚的に強調して伝える |

それぞれについて簡単に説明します。

### 1. 箇条書き

箇条書きや、情報の要点を簡潔に伝える手法です。順序があるものと、ないものがあります。

文章を書いていて要点がつかめなかったり、文章が長くなってしまったときは、箇条書きにすると伝わりやすくなったりします。

### 2. 表

表は、情報をいくつかの項目を元に整理して伝える手法です。

ある項目について、いくつかのものを比較するときなどに、文章よりも伝わりやすくなることがあります。

### 3. ソースコード

技術的な内容によっては、文章で説明するよりも、実例を見た方が早いことがあります。

実装例やコマンドの実行例などを提示することで、文章と合わせて読者に理解を促すことができます。

### 4. 図

説明したいことを、図を用いて視覚的に伝える手法です。図があることで、文章と合わせて理解を促すことができます。

特に理解が難しい内容を説明する場合に、図による説明が有効になります。

例えば、処理の流れはシーケンス図を用いたりします。シーケンス図については「[PlantUML入門①: シーケンス図の書き方](/posts/plantuml-sequence-diagram)」をご覧ください。

### 5. メッセージ

補足情報や注意事項などを、文章とは別の見た目で視覚的に強調して伝えます。特に気をつけてほしいことを伝えるときなどに効果的な手法です。

:::info
### いろんな表現方法を織り交ぜる

文章が続くと、理解が難しいだけでなく、視覚的にも締まりがなくなってしまいます。箇条書きや表など、上記の表現方法を適切に織り交ぜることで、分かりやすく、視覚的にも読みやすい開発ドキュメントにつながります。
:::

## その他の表現方法

ここまでで説明した5つが基本的な表現方法になります。もちろん、他にもいろんな表現方法があります。

次に説明する方法は、効果的ではありますが、サイト側の実装コストや、コンテンツの制作コストが大きくかかってきます。

コストをかけてでも分かりやすく伝えたい場合に検討するとよさそうです。

| 番号 | 表現方法 | 概要 |
| :---: | --- | --- |
| 6 | 用語集 | 読者によって分かりづらい用語を説明する |
| 7 | 動画 | 情報を動画で説明する |
| 8 | プレイグラウンド | ウェブ上で動作を確認できる機能を提供する |

こちらもそれぞれについて簡単に説明します。

### 6. 用語集

読者にとって分かりづらい用語を、ツールチップなどで補足します。

開発ドキュメントにいろんな読者がいる場合、習熟度が低い人に合わせて説明しようとすると、文章が冗長になることがあります。かといって、説明しないと理解しづらくなります。

この場合、用語集があることで、必要な人にだけ補足することができます。

### 7. 動画

動画はその名の通り、文章だけで伝わりづらいことを動画で説明します。例えば、[Contentful](https://www.contentful.com/developers/docs/extensibility/app-framework/tutorial/)や[Terraform](https://learn.hashicorp.com/tutorials/terraform/infrastructure-as-code)は動画によるチュートリアルを提供しています。

特にチュートリアルのような、読者にとって入り口となるテーマで効果的です。

動画は制作コストがかかるのはもちろん、内容が変わったときに修正しづらいという欠点もありますが、ポイントを絞って提供するとよさそうです。

### 8. プレイグラウンド

プレイグラウンドは、ライブラリやAPIなどの動作をウェブ上で試す機能になります。例えばStripeは[Payment Element](https://stripe.com/docs/payments/payment-element)という機能のプレイグラウンドを提供しています。

機能を実際に体験できるので、もっとも伝わりやすい表現方法といえます。開発コストがかかりますが、これも可能であればポイントを絞って提供したいです。

## おわりに

開発ドキュメントは、文章だけだとどうしても伝わりづらいです。箇条書きや表といった表現方法をうまく活用することで、分かりやすい文章を、早く書くことができます。

基本的な表現方法だけでも、しっかり押さえておきたいところです。

開発ドキュメントは、文章だけだと分かりづらかったり、読みづらい文章になってしまいます。分かりやすい文章を、それも早く書くには、箇条書きや表のような「表現方法」を押さえておくことがポイントです。この記事では、文章における表現方法についてまとめます。

表現方法のイメージ

開発ドキュメントの文章における表現方法【箇条書き・表など】

私はテクニカルライターとして、開発ドキュメントを書いています。開発ドキュメントを書く上で、文章をよりよくするには、「校正」というプロセスが必要になります。

この校正というのは、誤字・脱字を直したり、文章全体を読みやすくしたりする、という作業になります。

この校正は、もちろん目視でやることもできますが、自動で行うこともできます。この記事では、校正とは何か、そしてこの校正を自動で行う方法として「[textlint](https://textlint.github.io/)」というツールの説明をします。

この記事を読むことで、よりよい文章を効率的に書けるようになるきっかけになれたらと思います。

::author

#### 目次

## 校正とは何か

まず校正について整理します。校正とは、文章の誤りを正す作業になります。例えば誤字・脱字を見つけて、それを直す作業が校正です。

この校正は、元々は「原稿と製作物の文字に違いがないかを、一字ずつ確認する作業」のことを意味していました。

他にも校正には、次のような「読みやすい文章にするための修正」も含まれます。

- 一文が長すぎないか
- ら抜き言葉はないか
- 敬体・常体を混ぜていないか

このように、よりよい文章にするために必要なプロセスが校正になります。

開発ドキュメントを書くときはもちろん、ブログだったり、Twitterだったりなど、文章を書くときにこの校正という作業をすることによって、よりよい文章につながっていきます。

## 自動校正ツール

この校正という作業は、目視で行うことができます。私もよく目視で校正を行います。

ただ目視だけだと、どうしてもミスが発生してしまいます。人がやる以上、このミスは避けられないと思います。

ここで役に立つのが校正ツールです。校正ツールでは、誤字・脱字や、変換ミスなどを検出することができます。

例えば校正ツールには、次のようなツールがあります。

- [Enno](https://enno.jp)
- [プレスリリース校正ツール](https://www.value-press.com/proofreader)

ただ、これらのツールは、フォームに文章を入力しないといけません。手間がかかりますし、サーバに文章が送られることにもなります。企業によっては、情報管理の関係上こういったツールを採用できないかもしれません。

他にも、「校正を自動で行いたい」とか、「もっと広いルールで校正をしたい」という要望があるかもしれません。それができるのが「textlint」というツールになります。

## textlintとは

![textlintのトップページ](//images.ctfassets.net/pppgbgujcovf/6FkDZial7Z5Xhlz1uogPxx/b8b39903525d925c93f5b25c1ac2c58c/textlint.png)
:img-caption{text="textlintのトップページ"}

[textlint](https://textlint.github.io/)は文章やMarkdownのための校正ツールになります。例えばテキストエディタで文章を書くとき、ルールに従ってミスを指摘してくれます。

例えば「一文が長過ぎる」とか「ら抜き言葉がある」といったミスを自動で検出してくれます。その場で修正することによって、よい文章を効率的に書けるようになります。

このtextlintを使うことで、次のようなメリットがあります。

- さまざまなルールがある
- 日本語のルールが豊富
- ルールをまとめたプリセットがある
- エディタ向けの拡張がある
- 自動で校正してくれる
- 設定を共有できる
- 無料で利用できる

これらのメリットについて、簡単に整理します。

textlintでは、誤字・脱字だけでなく、広いルールで校正をすることができます。ルールの一覧は次のページで公開されています。ご覧の通り、日本語のルールがとても豊富です。これは作者が日本の方ということもあるかもしれません。

- [Collection of textlint rule](https://github.com/textlint/textlint/wiki/Collection-of-textlint-rule)

ルールがたくさんあってどれを選べばいいかわからない、というときは、ルールをまとめた「[プリセット](https://github.com/textlint/textlint/wiki/Collection-of-textlint-rule#rule-presets-japanese)」というものを使うといいと思います。開発ドキュメントを書く場合は、[技術文書向けのプリセット](https://github.com/textlint-ja/textlint-rule-preset-ja-technical-writing)を使うといいです。これひとつ導入することで、オールインワンでルールが揃います。

またVS CodeやVimのようなエディタ向けの拡張機能もあります。この拡張機能を導入することで、エディタで文章を書いているときに、自動でミスを指摘してくれます。

textlintのルールは、ファイルとしても共有できます。Gitなどで管理すれば、チームの中で同じルールをもとに文章を書くことができます。つまり、チーム内で文章の品質を一定以上に保つことができます。

ここまでできて、textlintはOSSとして公開されています。つまり無料で利用することができます。

企業等でtextlintを導入する場合は、[作者のスポンサー](https://github.com/sponsors/azu)になることで支援することもできます。ぜひ検討してみてください。

## textlintの導入方法

ここではGitで管理しているプロジェクトにtextlintを導入します。あわせて、技術文書向けのプリセットを導入します。これは次のコマンドを実行します。

```bash
$ npm install --save-dev textlint textlint-rule-preset-ja-technical-writing
```

これだけで、textlintの実行環境と、必要なルールが揃います。

次にtextlintの設定ファイルを準備します。`.textlintrc`というファイルを作成して、次のように記述します。

```json
{
  "rules": {
    "preset-ja-technical-writing": true
  }
}
```

あとは、次のコマンドで校正を実行します。校正したいファイルを`file.md`だとすると、

```bash
$ ./node_modules/.bin/textlint file.md
```

となります。textlintの始め方について詳しくは、公式ドキュメントの「[Getting Started with textlint](https://textlint.github.io/docs/getting-started.html)」をご覧ください。

基本的には、上記のようにコマンドを実行することで校正を行いますが、テキストエディタの拡張機能を入れることで、文章を入力中に自動で校正をしてくれます。

代表的な拡張機能を次に紹介します。

- VSCode: [vscode-textlint](https://marketplace.visualstudio.com/items?itemName=taichi.vscode-textlint)
- Atom: [linter-textlint](https://atom.io/packages/linter-textlint)

## textlintのカスタマイズ方法

実際にtextlintを実行したら、指摘がたくさん入るかもしれません。書いている文章によっては、「ルールが合わない」ということが出てきます。

この場合は、文章をルールに合わせる必要はありません。textlintでは、ルールの方を細かくカスタマイズすることができます。

例えば[技術文書向けのプリセット](https://github.com/textlint-ja/textlint-rule-preset-ja-technical-writing)の場合、一文の長さは100文字となっています。これを120文字にするときは、次のように設定します。

```json
{
  "rules": {
    "preset-ja-technical-writing": {
      "max": 120
    }
  }
}
```

カスタマイズ方法について詳しくは、「[Configuring textlint](https://textlint.github.io/docs/configuring.html)」をご覧ください。

## CIによる自動校正

textlintは手元で実行するだけでも効果的ですが、GitHub ActionsやCircleCIなどのCI環境で設定すると、ミスを含んだ文章を公開することを防げます。

CIによる自動構成については、次の記事が参考になります。CIの設定だけでなく、textlint自体の設定についても参考になるので、ぜひご覧ください。

- [textlint + Reviewdog + GitLab CI でアドベントカレンダーの校正をした話](https://www.forcia.com/blog/002374.html)
- [GitHub ActionsでZennブログの校正を自動化してみた](https://zenn.dev/yuta28/articles/blog-lint-ci-reviewdog)

## おわりに

よりよい文章にするには、校正という作業が必要になります。この校正を自動で行うツールとして、textlintを紹介しました。

この記事が、よりよい文章になるきっかけになればうれしいです。

校正は、誤字・脱字を直したり、文章全体を読みやすくしたりする、という作業になります。この校正は、もちろん目視でやることもできますが、自動で行うこともできます。この記事では、校正とは何か、そしてこの校正を自動で行う方法として「textlint」というツールの説明をします。

校正のイメージ

開発ドキュメントの文章を自動で校正する方法【textlint】

私はテクニカルライターとして働いています。開発ドキュメントを書くときは、基本的にアウトラインを書いています。

以前は、わかりやすい文章がなかなか書けませんでした。書けたとしても、とても時間がかかっていました。

「何とかしたい！」と思い、試行錯誤しました。その結果、自分なりのやり方を体系化でき、一定以上の品質の文章を、早く書けるようになりました。

この記事を読むことで、わかりやすい開発ドキュメントを書くきっかけになればと思います。

::author

#### 目次

## アウトラインとは何か

アウトラインとは、箇条書きで文章の骨組みを表現したものをいいます。最終的には、この骨組みに肉付けをしていくことによって、文章になります。

アウトラインは、文章の全体像を設計するのに役立ちます。基本的には、文章を書くときはまずアウトラインを書くことになります。

## アウトラインを書く必要性

アウトラインは、次の二つのために書きます。

1. 読者に伝わる文章にするため
2. 文章作成にかける時間を短くするため

それぞれについて、簡単に説明します。

### 1. 読者に伝わる文章にするため

アウトラインでは、文章の順序を仮決めして、読者の視点でわかりやすいかどうかを確認していきます。このため、話を入れ替えたり、補足したり、といった修正が簡単にできます。

アウトラインを書かずに、いきなり文章を書き始めてしまうと、次のような問題が生まれやすいです。

- あるところは詳しいけど、あるところは説明が足りていない
- 文章の順序がわかりづらい

文章を書いた後だと、文章が長く、俯瞰して確認しづらくなります。こうならないためにも、アウトラインの時点でわかりやすいかどうかを確認することが大切になってきます。

### 2. 文章作成にかける時間を短くするため

いきなり文章を書いてしまうと、修正が難しくなります。文章は文脈を含めて書くので、単純に構成を並び替えると、文脈がおかしくなってしまうからです。

早く書こうと思って文章から書きはじめたつもりが、結果的に、文章を書くのに時間がかかってしまいます。

よりよい文章を早く書くためにも、アウトラインを書くことが重要になってきます。

## アウトラインの書き方

アウトラインは、次の三つを意識して書いていきます。

1. 見出しで全体像を設計する
2. 見出しごとの内容を書く
3. 読者にとってわかりやすくする

ひとつずつ説明していきます。

:::info
### アウトラインを書く前に企画をしておこう

よいアウトラインを書くためには、企画として、あらかじめ「読者」と「伝えたいこと」を決めておく必要があります。企画について詳しくは、「[開発ドキュメントを書く前に決めるべき3つのこと【企画編】](/posts/how-to-plan-document)」をご覧ください。
:::

### 1. 見出しで全体像を設計する

アウトラインは、まず箇条書きで見出しを書いていきます。

必要に応じて大見出し、中見出し、小見出しのようにレベルを使い分けます。このとき、インデント（字下げ）でレベルを表現します。

この見出しは、実際の目次になるイメージで設計していきます。

### 2. 見出しごとの内容を書く

次に見出しごとに内容を書いていきます。アウトラインはあくまで骨組みなので、肉付けはしないようにします。

アウトラインの段階で詳細まで書いてしまうと、修正がしづらくなってしまいます。また、文章を書くときに、表現の自由が利かなくなったりします。

### 3. 読者にとってわかりやすくする

はじめに押さえておきたい考え方として、あなたが書きたいことと、読者にとってわかりやすいことは違います。

まずはあなたが書きたいように書いてもいいですが、書き終えたら、読者にとってわかりやすいよう、順序を変えたり補足したりしてみます。

## アウトラインが完成する条件

アウトラインは、次の二つを満たすまで修正を繰り返していきます。

- 伝えたいことを伝えられているか
- 読者にとってわかりやすいか

ポイントとしては、一度アウトラインを書き終えたら、一晩寝かせてみます。こうすることで、フラットな目線で推敲できるようになります。

ここまでできれば、文章を書く準備が整いました。

実際に文章を段階になると、アウトラインにないことを書くこともありますが、これはこれで問題ありません。

少なくとも、アウトラインを書くことで、わかりやすい文章を早く書くための土台ができます。

## アウトラインを書くためのツール

アウトラインは、箇条書きで、かつインデントを用いながら書いていきます。つまり、次の条件を満たせば、どんなツールでも問題ありません。

- 改行時にリストになること
- インデントが保たれること
- 編集がしやすいこと

私はmacOS標準のメモアプリを使っています。ツールについては、あなたの使いやすいものを探してみてください。

## 例：この記事のアウトライン

参考までに、この記事を書く前に書いたアウトラインを以下に紹介します。開発ドキュメントとはちょっと違いますが、参考になればうれしいです。

```
* リード
    * テクニカルライターとして働いている
    * 開発ドキュメントを書くときはアウトラインを書いている
    * 以前はわかりやすい文章が書けなかった
    * またとても時間がかかっていた
    * 今では自分なりにやり方を体系化した
    * ある程度の質のある文章を早く書けるようになった
    * この記事を読めば、わかりやすい開発ドキュメントを早く書けるようになる
* アウトラインとは何か
    * 文章の骨組みを箇条書きにしたもの
    * 最終的にはこの骨組みに肉付けしてくことによって文章となる
    * 文章の全体像を設計するのに役立つ
    * 基本的には、文章を書くときはまずアウトラインを書く
* アウトラインを書く必要性
    * 次の二つ
    * 伝わる文章にするため
        * 話の順序を仮決めして、読者の視点でわかりやすいかを確認する
        * 入れ替えたり補足したり、といった修正が簡単にできる
        * いきなり書き始めると：
            * あるところは詳しいけど、あるところは説明が足りない
            * 順序がわかりづらい
        * といった問題が生まれやすい
        * 書いた後だと文章が長く、俯瞰して確認しづらい
    * 作成にかける時間を短くするため
        * いきなり文章を書くと、修正が難しい
        * 文章は文脈を含めて書く
        * 並び替えると文脈がおかしくなったりする
        * 結果的に時間がかかる
        * よい文章を早く書くためにもアウトラインは重要
* アウトラインの書き方
    * 前提→読者、伝えたいことを決めておく
    * アウトラインは次の三つを意識して書く
    1. 見出しで全体像を設計する
        * 箇条書きで書く
        * 必要に応じて大見出し、中見出し、小見出しを使う
        * インデント（字下げ）で表現する
        * 実際の目次になるイメージ
    2. 見出しごとの内容を書く
        * 内容を書いていく
        * アウトラインはあくまで骨組み
        * 肉付けしない
        * 詳細まで書くと修正しづらい
        * 文章を書くとき、表現に自由が利かない
    3. 読者にとってわかりやすくする
        * あなたが書きたいことと、読者にとってわかりやすいことは違う
        * まずは書きたいように書いていい
        * 読者にとってわかりやすいよう、順序を変えたり補足したりする
* アウトラインの作成が完了する条件
    * 次の二点を満たすまで修正する
        * 伝えたいことを伝えられているか
        * 読者にとってわかりやすいか
    * ポイント→寝かせる
    * フラットな目線で推敲できる
    * これができれば、文章を書く準備が整った
    * 実際に文章を書く段階になると、アウトラインにないことを書くこともある
    * 問題ない
    * 現時点で考えられるよりよいアウトラインを目指す
    * アウトラインを書くことで、早くわかりやすい文章が書ける
* アウトラインを書くためのツール
    * アウトライン→箇条書き、かつインデントで書いていく
    * 以下の条件を満たせば何でもよい
        * 改行時にリストになる
        * インデントが保たれる
        * 編集がしやすい
    * 私はmacOS標準のメモアプリを使っている
* 例
    * この記事で書いたアウトライン
    * 開発ドキュメントではないが、参考になると思う
* おわりに
    * アウトラインを書くと伝わる文章を早く書ける
    * 箇条書きで、見出しと内容を書く
    * 読者の視点でわかりやすいように書く
```

## おわりに

アウトラインを書くと、伝わる文章を早く書けるようになります。このアウトラインは、箇条書きで、見出しと内容を書いていきます。

アウトラインを書くときは、読者の視点でわかりやすいように書くことが大切です。

アウトラインとは、箇条書きで文章の骨組みを表現したものをいいます。最終的には、この骨組みに肉付けをしていくことによって、文章になります。アウトラインは、文章の全体像を設計するのに役立ちます。基本的には、文章を書くときはまずアウトラインを書くことになります。

アウトラインのイメージ

開発ドキュメントにおけるアウトラインの書き方

私はテクニカルライターとして働いていて、複数のチームと連携をしながら開発ドキュメントを書いています。

今はある程度スムーズに開発ドキュメントを書けていますが、以前は公開までの作業をうまく進められないことがありました。

例えば、開発ドキュメントを書くために必要な情報がわからなかったり、公開直前のレビューで差し戻されたり、レビュワーの方にとって優先度が低く、なかなかレビューが進まなかったり。

こういった問題のほとんどは、文章を書く前に、要件をしっかりと整理することで解決します。

この記事では、周囲の状況に左右されず、効率的に開発ドキュメントを公開までもっていくための方法についてまとめています。

::author

#### 目次

## 開発ドキュメントの作成フロー

まず、そもそも「どうやって開発ドキュメントを作るのか」について整理しておきます。詳細については別の記事に書く予定ですが、概要は次のような感じになると思います。

| 手順 | 項目 | 概要 |
| :---: | --- | --- |
| 1 | チケット化 | 開発ドキュメントに対する要求が生まれる |
| 2 | 要件整理 | チケット作成者からの要件を整理する |
| 3 | 企画 | [読者からの要求を整理する](/posts/how-to-plan-document) |
| 4 | アウトライン作成 | 文章の骨組みを作る |
| 5 | 執筆 | 文章を作成する |
| 6 | 推敲 | 文章を練り直す |
| 7 | レビュー | 関係者からのレビューを受ける |
| 8 | 公開 | 文章を公開する |

書くことが決まった後にやるのが、この記事で説明する要件整理になります。

## 要件整理とは何か

要件整理とは、チケット作成者からの要件を整理することをいいます。具体的には、チケットの対応範囲やスケジュール、関係者などを一枚のページにまとめます。

「こういう文章を書いてほしい」という要求があった時点では、まだその要件は曖昧なことが多く、その状態で文章を書きはじめてしまうと、作業が行き当たりばったりになってしまう可能性があります。

この曖昧な状態から、実際に開発ドキュメントのを書く上で必要な情報を整理していくのが要件整理です。

詳細は後述しますが、具体的には次のようなことを決めていきます。

| 手順 | 項目 | 概要 |
| :---: | --- | --- |
| 1 | 概要 | チケットの概要 |
| 2 | 関連情報 | チケットや関連ページへのリンクなど |
| 3 | スケジュール | 公開までのスケジュール |
| 4 | 関係者 | チケット作成者や企画、開発担当者など |
| 5 | スコープ | チケットの対応範囲 |
| 6 | メモ | 文章を書くのに必要な、網羅的な情報 |
| 7 | 議事録 | チケットに関するミーティングの議事録 |
| 8 | 疑問点 | チケットを進める上で生まれた疑問 |

要件整理は、自分が見るのはもちろんですが、他の関係者も見る重要な資料になります。例えば、レビュワーはこの要件整理を見ることで、スムーズにレビュー作業に入ることができるようになります。

## 要件整理の必要性

要件整理をする目的は、開発ドキュメントを公開するまでの不確実性をなくして、効率的に作業を進められるようにすることです。

開発ドキュメントを書くときは、いろんな問題があると思います。例えば、

1. 何を書けばいいのかわからない
1. 書いた後で差し戻されてしまう
1. 公開前になって、間に合いそうにないことに気づく

などがあります。

1については作業の対応範囲が不明瞭だったり、2はレビュアーが誰かわからなかったり、3はスケジュール管理上の問題だったりします。

他にも、レビュー時にレビュアーがチケットの内容を把握するのに時間がかかることも問題になりがちです。

しっかりと要件を整理しておけば、こういったたいていの問題は防ぐことができます。

## 要件を整理する方法

要件整理は、「このページを元にすれば問題なく文章が書ける」という網羅性が重要になります。開発ドキュメントを書く上で、必要な情報をまとめていきます。

要件整理は、自分だけでなくレビュアーなど他の人も見る可能性がある文書になります。このため、社内Wikiなどに書くとよいでしょう。

参考までに、ドキュメント管理ツールであるNotionで要件を整理した例を次に示します。

![Notionで要件整理をした例](//images.ctfassets.net/pppgbgujcovf/23iauXIrWYsZyMO5PCJPGN/52cc4dda31207a0f2a9f746d78a1d3c6/organize-example.png)
:img-caption{text="Notionで要件整理をした例"}

### 1. 概要

チケットの概要を1〜3行程度で簡潔にまとめたものです。チケットがどういうものかを把握するのに役立ちます。

自分だけでなく、レビュアーが読むこともふまえて記述します。

### 2. 関連情報

開発ドキュメントを書くにあたって役に立つ関連情報を表にまとめます。例えば、

- チケットへのリンク
- 仕様や議事録などのページへのリンク
- コミュニケーションツールへのリンク（Slackのちゃんねるなど）
- 公開日
- 対応する言語

などを書きます。

### 3. スケジュール

開発ドキュメントを公開するまでの具体的なスケジュールを決めます。チケットが作られたタイミングでは、決まるとしても公開日くらいだと思います。

これをもっと細分化して、例えばいつまでにドラフトを書くか、レビューを依頼するかなどの日を決めます。こうすることで、関係者への期待値を調整することができます。

進捗を共有したい重要なミーティングがあれば、その日付を書いておくのもよいです。

### 4. 関係者

チケットを進める上で関係する人を表にまとめます。ここでまとめた人を対象に、進捗を共有したり、レビューを依頼したりします。

例えば、次のような役割の方を書いていきます。ここは製品によって変わってくると思います。

- チケット作成者
- 企画担当者
- 開発担当者
- レビュワー
- QA担当者

### 5. スコープ

このチケットで何をするのか、あるいは何をしないのかを決めます。また、項目ごとに優先度を決めます。

こうすることで、文章を書いた後に「これを書いてほしかった」「これは書かないでほしかった」といった期待値に関する問題を防ぐことができます。

優先度については、次のようなラベルをつけるとわかりやすいです。

| ラベル | 概要 |
| --- | --- |
| Must | 必ず対応すること |
| Nice to have | 可能であれば対応すること |
| Out of spec | このチケットでは対応しないこと |

### 6. メモ

文章を書く上で必要な情報を網羅的にまとめていきます。例えばチケットが生まれた背景や、具体的な仕様、その他の補足情報などを書いていきます。

ここも自分だけでなくレビュアーが見ることを意識して、わかりやすいように書きます。

### 7. 議事録

チケットに関するミーティングを行うことがあると思います。そのときの議事録を書いておきます。開発ドキュメントを書くときの資料になったりします。

### 8. 疑問点

チケットが生まれた段階では、疑問点がたくさんあると思います。例えば、

- どのページに書けばいいのか
- レビュアーは誰なのか
- いつ公開すればいいのか

などです。こういった要件についての疑問を洗い出します。ここで洗い出しつつ、ミーティングの場などで質問して、解決をめざします。

この疑問点を洗いだせるか、早い段階で解決できるかが、スムーズに作業を進める上で重要になってきます。

## おわりに

他にも、目次や更新履歴などを書いておくと、ページとしての使いやすさが高まります。

開発ドキュメントを書く上では、まず要件を整理しておくと、公開までの障壁がなくなり、スムーズに公開まで進められるようになります。

開発ドキュメントの作成をうまく進められなくて悩んでいましたら、ぜひ参考にしてみてください。

「開発ドキュメントを書くために必要な情報がわからない」「公開直前のレビューで差し戻される」といった問題のほとんどは、要件をしっかりと整理することで解決します。この記事では、周囲の状況に左右されず、効率的に開発ドキュメントを公開までもっていくための方法についてまとめています。

物事を整理するイメージ

開発ドキュメントの要件を整理する方法

私はテクニカルライターとして開発ドキュメントを書いています。文章を書く上で「もっと読者の開発体験を高めるにはどうすればよいか」という問いに対して、自分なりの考えが固まってきたので、この記事でまとめてみます。

結論を先にいうと、文章を書く前に、

1. その文章の読者は誰か
1. 読者の悩みは何か
1. 悩みを解決する方法

を企画します。やること自体はすごくシンプルで、時間もそんなにかかりません。一方で、この3つを企画するかどうかで、文章のわかりやすさが大きく変わってきます。

この記事を読むことで、文章を書く前に考えるべきことがわかり、もっとわかりやすい開発ドキュメントが書けるようになると思います。

::author

#### 目次

## なぜ企画が必要なのか

まず、この記事を書こうと思った背景から説明します。

開発ドキュメントを書くときは、昔はいきなり文章を書きはじめていました。ただ実際には、「文章を書く前に考えること」というのがたくさんあります。

文章というのは、もちろん読む人がいるんですが、読む人には「その文章を読む目的」というのがあります。例えばエンジニアの方で、開発中にエラーが出てしまって、それをどう解決すればいいかわからない、という悩みがあったりします。

こういった悩みを解決するために、読者は文章を読みます。読者や悩みを決めないまま文章を書いてしまうと、結局何がいいたいのか、記事を通して何を伝えたいのかがわからない、というような問題が出る可能性があります。

こうならないためにも、読者とその悩み、加えて悩みをどう解決するか、ということを決めることが大切になってきます。

:::info
### リーンスタートアップを元にしています

プロダクト開発の現場においても、まずはじめに顧客を決めて、顧客が抱える課題を見つけ、課題を解決する方法を決める、という「[リーンスタートアップ](https://ja.wikipedia.org/wiki/リーンスタートアップ)」という手法があります。この記事の内容は、リーンスタートアップを開発ドキュメントに応用した手法となります。
:::

## 開発ドキュメントを書く前に決めるべきこと

ここまでで書いた通り、文章を書く前に企画をすること、つまり読者とその悩み、そして解決策を決めることが大切です。この3つの項目の概要は、それぞれ次のようになります。

| 手順 | 項目 | 例 |
| :---: | --- | --- |
| 1 | 読者は誰か | プログラミングを学びはじめたばかりの人 |
| 2 | 読者の悩みは何か | コードを実行しようとしたらエラーが表示された |
| 3 | 悩みを解決する方法 | エラーが出た原因と解決策を説明する |

この3つの項目について、ひとつずつ見ていきます。

### ① 読者は誰か

読者というのは「その文章を誰が読むのか」ということになります。企画では3つの項目を決めますが、この読者を決めることが特に重要になってきます。

文章というのは、もちろん読む人に向けて書きますが、例えば読む人が初学者と上級者では、伝わる言葉が大きく変わってきます。

例えばRubyには[JITというコンパイル方式](https://www.publickey1.jp/blog/21/railsjitruby_311.html)があります。低レイヤーに詳しい方だと「JIT」という用語はふつうに使ってもいいと思いますが、プログラミングをはじめたばかりの初学者の方だと、そもそも「コンパイルとは何か」というところから説明しないといけないかもしれません。

このように、読者によって文章や構成がまったく変わってきます。わかりやすい文章を書くためには、はじめに読者をしっかり決める、ということが大切になってきます。

### ② 読者の悩みは何か

読者を決めたら、次に読者の悩みを考えます。人は文章を読むとき、基本的には何かしらの悩みをもっています。例えば開発ドキュメントは、開発をしていてつまずいたりとか、つくりたいものがあるからつくり方を学びたい、といったときに読むと思います。

これは開発ドキュメントに限らず、例えばニュース記事を読むときも「暇をつぶしたい」という悩みがあるといえます。

はじめに決めた読者の、どういう悩みについて書くのか。これによって、読者が文章を読んでくれるかどうかが決まります。

悩みを決める上でのポイントとして、ひとつのページで解決する悩みはシンプルにします。ひとつのページでたくさんの悩みを解決しようとすると、文章が長くなってしまい、わかりづらくなったり、結局何がいいたいのかがわからなくなったりしてしまいます。

### ③ 悩みを解決する方法

読者と、読者の悩みが決まったら、最後に解決策を決めます。これは「読者の悩みをどう解決するか」ということで、書く内容や文章の構成、伝え方などを決めていきます。

伝え方というのは、文章だけではなく、画像や表、箇条書きといった「読者にとってわかりやすい表現方法」についても考えます。

実際に文章を書くときは、この解決策で決めたことをもとに書いていくことになるので、文章を書くときをイメージしながら解決策を決めるといいです。

## おわりに

この記事では、文章を書くにあたって「あらかじめ決めておくべき3つのこと」を説明しました。つまり読者とその悩み、そしてその解決策を決める、ということです。

これを決めた上で、はじめて文章を書きはじめる、ということになります。これをすることによって、読者にとってわかりやすいことばで、悩みを解決してくれる開発ドキュメントになると考えています。

私はテクニカルライターとして開発ドキュメントを書いています。文章を書く上で「もっと読者の開発体験を高めるにはどうすればよいか」という問いに対して、自分なりの考えが固まってきたので、この記事でまとめてみます。

企画のイメージ

開発ドキュメントを書く前に決めるべき3つのこと【企画編】

私はテクニカルライターとして仕事をしています。文章を書くのはもちろんですが、これまでプロダクトマネージャーやエンジニアだったという経験を生かして、開発ドキュメントサイトの構成やコンテンツについても考えることがあります。

この中で、

> わかりやすい開発ドキュメントサイトにするには、どうすればよいのか？

という問いについて考えることがあります。つまり「どのようなコンテンツを提供するか」という問題です。

このことについて、ひとことで「開発ドキュメントサイト」といっても、いわゆるドキュメントの他に、チュートリアルやリファレンスといった、いろんなコンテンツがあると思います。

このことをふまえて、開発ドキュメントサイトに必要なコンテンツを整理してみました。開発ドキュメントサイトをつくろうと思ったときに、「どういうコンテンツがあればいいのか」ということを考えるときの参考になればと思います。

::author

#### 目次

## 対象とするコンテンツ

開発ドキュメントサイトにおけるコンテンツを整理するにあたって、まずどういうコンテンツがあるかを洗い出してみました。これについては、以前「[開発ドキュメントサイトをつくるときの参考になるサイト](/posts/reference-sites-for-documentation)」という記事を書きました。

この中で、開発ドキュメントサイトには次のようなコンテンツがある、ということを学びました。

* チュートリアル
* ドキュメント
* リファレンス
* 用語集
* FAQ
* ショーケース
* 実装例
* コミュニティ
* プレイグラウンド

こういったコンテンツが、どんな読者に向けたコンテンツなのかを整理していきます。

## 読者の種類

少し前置きが長くなってしまいますが、コンテンツを整理する前に、今度は読者について考えてみます。

開発ドキュメントサイトを見る読者には、いろんな層があると思います。例えば初学者や中級者などですね。この層によって、見るコンテンツは大きく変わってきます。

例えば初学者は、製品に関する知識がまだほとんどないので、例えばチュートリアルのようなコンテンツを見ると思います。一方で上級者になってくると、チュートリアル系のコンテンツはほとんど見ないでしょう。

このような感じで、読者の習熟度によって開発ドキュメントサイトの中で見るコンテンツというのは大きく変わってきます。つまりコンテンツを考える前に、そもそも「どういった読者が存在し得るのか」ということを知っておく必要があります。

この記事では、開発ドキュメントサイトを読む読者の分類について、次のように分けています。この初級者・中級者・上級者という分類で、今度はコンテンツの方を整理していきます。

| 習熟度 | 製品に対する知識 |
| --- | --- |
| 初級者 | その製品に関する知識がほとんどない |
| 中級者 | その製品に関する基本的な知識をもっている |
| 上級者 | その製品を活用した実践的なアプリケーションを構築できる |

## コンテンツの種類まとめ

それでは、開発ドキュメントサイトにおけるコンテンツの種類と、その対象となる読者・重要度・目的を表でまとめてみました。

:::notice
### 注意

この表でいう重要度というのは、あくまで目安になります。ここは製品によって異なるので、参考程度にしてください。
:::

| 種類 | 読者 | 重要度 | 内容 |
| --- | --- | --- | --- |
| チュートリアル | 初級者 | ★★★ | 製品を用いた基本的なアプリケーション開発の方法を説明する |
| ドキュメント | 初〜上級者 | ★★★ | 製品の使い方を説明する |
| リファレンス | 中〜上級者 | ★★★ | 製品の詳細な仕様を示す |
| 用語集 | 初〜中級者 | ★★☆ | 読者にとってわかりづらい用語を説明する |
| FAQ | 初〜中級者 | ★★☆ | 読者の悩みとその解決策を示す |
| ショーケース | 初〜中級者 | ★★☆ | 製品で実現できることを紹介する |
| 実装例 | 中〜上級者 | ★☆☆ | ユースケースごとの実装方法を示す |
| コミュニティ | 中〜上級者 | ★☆☆ | 製品を取りまくコミュニティを紹介する |
| プレイグラウンド | 初〜中級者 | ★☆☆ | ウェブ上で製品を体験できるアプリケーションを提供する |

## 重要度 ★★★ のコンテンツ

それではまず、重要度の高いのコンテンツを見ていきます。このチュートリアルとドキュメント、リファレンスというのは、開発ドキュメントサイトにはとても重要な立ち位置にあります。

### チュートリアル

![チュートリアルの例](//images.ctfassets.net/pppgbgujcovf/3kbXEdD1C5l1Jp4sAQhICU/8c9fbd200c17b2996860117b66f9befc/tutorial-example.png)
:img-caption{text="チュートリアルの例（Next.js）"}

チュートリアルは、基本的には初心者向けのコンテンツになってきます。内容としては、製品を用いた基本的なアプリケーション開発の方法について説明します。

読者が製品に定着するには、読者自身の「開発を通した成功体験の積み重ね」というものがすごく大切になってきます。このため、製品をはじめて利用する読者にとって「ひとつ目の成功体験を積んでもらう」、ということが大きな目的になってきます。

また、例えばチュートリアルの中でドキュメントやリファレンスへのリンクを貼ることで、開発ドキュメントサイト全体の構成を知ってもらう、ということにも役立ちます。

[Next.js](https://nextjs.org)や[Terraform](https://www.terraform.io)のように、チュートリアルへの導線を強調している開発ドキュメントサイトもたくさんあります。

### ドキュメント

![ドキュメントの例](//images.ctfassets.net/pppgbgujcovf/5XhYU7TYaNLDy6YH5tqU4a/9f4e6cf6523fbe2ec63ac2c6303bab04/document-example.png)
:img-caption{text="ドキュメントの例（Contentful）"}

ドキュメントは、チュートリアルを終えた人向けのコンテンツになります。主な目的としては「製品の使い方を説明する」ということになってくると思います。「いわゆるドキュメント」というとこれを想像するような、基本的なコンテンツになります。

ドキュメントの性質は、大きく分けると次の3つに分かれます。

| 種類 | 内容 |
| --- | --- |
| Getting Started | はじめるとき、更新するとき等に見るもの |
| Basics | 基本的なアプリケーション開発をするために十分なもの |
| Advanced | 実践的なアプリケーション開発に役立つもの |

この3つは、読者や利用頻度が変わってきます。例えば、Getting Startedにはインストール方法やアップグレードガイドなどが当てはまりますが、これらは頻繁に見るページではないと思います。一方で、Advancedの内容は、初級者の読者には難しすぎてよくわからないかもしれません。

こういったページをひとつのコンテンツとしてまぜてしまうと、読者は何を見ればいいかわからず、開発体験が下がってしまう可能性があります。

### リファレンス

![リファレンスの例](//images.ctfassets.net/pppgbgujcovf/5sjEkvAEIyKxSfUQQ78zyB/1cfebf43071ceea8cd0d10b012f6b986/reference-example.png)
:img-caption{text="リファレンスの例（Stripe）"}

リファレンスは、製品のより詳細な仕様について書いたものになります。例としては、Stripeの[APIリファレンス](https://stripe.com/docs/api)があります。

リファレンスは、実際の開発において、悩みを解決するときにピンポイントで見るようなものになっています。製品によっては、「リファレンスがないと開発できない」というケースもあるでしょう。

リファレンスを提供できるような製品である場合は、リファレンスを提供することが必須になってくると思います。

## 重要度 ★★☆ のコンテンツ

次に重要度が中くらいのコンテンツを見ていきます。ここで紹介しているコンテンツは、どれも初級者にとっては重要なコンテンツになるので、コストをかけられるのであれば積極的に検討したいものになります。

### 用語集

![用語集の例](//images.ctfassets.net/pppgbgujcovf/4N7COKulbDqPqvL8VayjyB/d6c9bbbd349044cf999fed91f4cbb4ce/terms-example.png)
:img-caption{text="用語集の例（Stripe）"}

用語集は、開発ドキュメントサイトの中で使われている用語を簡潔に説明するためのコンテンツになります。

ドキュメントを書くときは、どうしても読者が分かりづらい用語を使う必要があるときが出てきます。こんなときに、例えば[Stripe](https://stripe.com/jp)ではツールチップで用語の概要を表示しています。

ドメイン知識が必要な製品の場合は、用語集があると読者に伝わりやすくなります。

### FAQ

![FAQの例](//images.ctfassets.net/pppgbgujcovf/5pMsArT1puCxMsZlC6DsWD/91abf222e0ce4e93c5fe07b4dcec22ae/faq-example.png)
:img-caption{text="FAQの例（Stripe）"}

FAQは、読者の悩みを起点にしたコンテンツになります。読者の悩みに対して一次回答をしつつ、あわせてドキュメントやリファレンスへのリンクを貼ります。こうすることで、読者は自分の悩みをベースに解決策を見つけることができます。

例えばStripeも[FAQ](https://support.stripe.com)というコンテンツをもっています。こんな感じで、よくある質問がある場合はFAQ をつくると、読者の利便性も上がりますし、問い合わせに回答するコストも下がります。

FAQに関しては検索性というものがとても大切になってくるので、そういう意味で開発・運用コストも高くなってしまいます。

### ショーケース

![ショーケースの例](//images.ctfassets.net/pppgbgujcovf/zQRPcFqMtjceZkNkEvrva/50f56ecb1b375a7e6811772745fe22ae/showcase-example.png)
:img-caption{text="ショーケースの例（Next.js）"}

ショーケースというのは、その製品を使っている製品を画像などで一覧にまとめたコンテンツになります。

「その製品を使うかどうか」というのは、つまり「つくりたいものを実現できるかどうか」が大切になるのですが、この導入事例を画像で提供すると、読者にとってとてもイメージしやすくなります。

このショーケースは、開発者だけではなく、企画担当者のようなビジネスメンバーにも参考になります。例えばNext.jsも[ショーケース](https://nextjs.org/showcase)を提供しています。

## 重要度 ★☆☆ のコンテンツ

最後に、重要度の低いコンテンツを見ていきます。ここで紹介するコンテンツは、もちろんあった方がよいですが、ここまでで紹介したチュートリアルや用語集などのコンテンツの方が、重要度はずっと高いです。

特定の読者層に対する開発体験を高めたいときなどに、導入を検討するとよさそうです。

### 実装例

![実装例の例](//images.ctfassets.net/pppgbgujcovf/2hQkQrYpuZXJc6rTodJw4e/11ec33cbea19de7f254ff38ebef81eec/example-example.png)
:img-caption{text="実装例の例（Next.js）"}

基本的なアプリケーション開発の外に出て、発展的な内容を開発しようとすると、ドキュメントの内容だけでは難しいことも出てきてしまいます。そんなときに、実装例があると開発者にとって参考になります。代表的なユースケースごとに実装例があるといいでしょう。

実装例はとても有用なコンテンツではありますが、一方で実際にコードを書いたり、あるいは「セキュリティ上の問題がないか」を考える必要があるなど、提供コストが大きくなってしまいます。

実装例についても、[Next.js](https://nextjs.org/examples)がコンテンツとして公開しています。

### コミュニティ

![コミュニティの例](//images.ctfassets.net/pppgbgujcovf/5DxolGx0Nl8y2YqcW6f8cs/62e7148c6a281e674531cc42737c07e3/community-example.png)
:img-caption{text="コミュニティの例（Nuxt）"}

コミュニティというのは、その製品を用いたライブラリなどを紹介するコンテンツになります。コミュニティのページを提供することは、もちろん利便性につながります。また、「製品自体の活発さ」というのも伝わります。

あとはコミュニティ向けにガイドラインをあらかじめ提供しておくと、コミュニティにいくらかの規律が生まれてきます。

例として、Nuxtが[Modules](https://modules.nuxtjs.org)という形でコミュニティのページを提供しています。

### プレイグラウンド

![プレイグラウンドの例](//images.ctfassets.net/pppgbgujcovf/6Gj9nUPdnNGHWM4R9IHn8Q/9853abf67f46f7ca9684ab5c9a3a9fe6/playground-example.png)
:img-caption{text="プレイグラウンドの例（Stripe）"}

プレイグランドは、ウェブ上で製品を試すことのできる機能を提供します。特に初学者にとっては、ウェブ上で手軽に製品について体験できると、理解がとても進むというメリットがあります。一方で、やはり提供コストが大きくなってきます。

製品の中で、特にインパクトの大きい機能についてはプレイグランドを提供することも検討するとよさそうです。例えばStripeは[Payment Element](https://stripe.com/docs/payments/payment-element)というプレイグランドを提供しています。

## 読者にあわせたコンテンツをつくる

ここまでで、開発ドキュメントサイトにおけるコンテンツの種類を整理してきました。この中では重要度について書きました。

ただ、最初にも述べましたが、読者というのは製品によって大きく異なります。大切なのは、その読者にあわせたコンテンツを提供することになります。

このため、まずはじめに

- 読者は誰なのか
- 読者は開発ドキュメントサイト上でどんな悩みを解決したいのか

ということをじっくりと考える必要があります。

例えば製品が初心者向けなら優しく丁寧に教えてあげたり、上級者向けの製品であれば前提知識を省略しつつ深い内容のコンテンツを提供する、といった感じです。

このように読者にあわせたコンテンツを作る、ということが大切になってくると思います。

## おわりに

この記事では、読者のレベルをもとにコンテンツを整理しました。その中でチュートリアルとドキュメント、リファレンスが重要だという話をしました。

まずは読者を理解した上で、読者が解決したい課題に応じて柔軟にコンテンツを設計できればと思います。

開発ドキュメントサイトに必要なコンテンツを整理しました。開発ドキュメントサイトをつくろうと思ったときに、「どういうコンテンツがあればいいのか」ということを考えるときの参考になります。

ドキュメントのイメージ

開発ドキュメントサイトにおけるコンテンツの種類まとめ

私は仕事で開発者向けにドキュメントを書いています。文章を書くのはもちろんですが、よりよい開発ドキュメントにするために、「コンテンツのあり方」についても考えることがあります。

「わかりやすい開発ドキュメントにはどんなコンテンツが必要なのか」「レイアウトはどうするべきか」など、コンテンツについて考える上で参考になるサイトを調べたので、この記事でまとめてみます。

よりよい開発ドキュメントづくりの参考になればうれしいです。

:::note
### 開発ドキュメントの定義

この記事でいう開発ドキュメントとは、開発者向けにライブラリやフレームワーク、APIなどを提供している製品についてのドキュメントをいいます。
:::

::author

#### 目次

## わかりやすい開発ドキュメントの条件

参考になりそうなサイトを見つけるにあたって、まず「わかりやすい開発ドキュメントの条件」を考えてみました。読み手として開発ドキュメントを読む上で、次の3つはほしいと思ったので、条件としました。

* スムーズに移動できるナビゲーションがあること
* 形を問わず、わかりやすいコンテンツを提供していること
* 文章が読みやすいこと

## 参考になるサイト

上で書いた条件をもとに、開発者向けにドキュメントを提供しているたくさんのサイトを見てみました。その中で、次の5つがとても参考になると思ったので紹介します。

1. [Next.js]
2. [Nuxt]
3. [Stripe]
4. [Contentful]
5. [Terraform]

ひとつずつ見ていきます。

### 1. Next.js

![Next.jsのトップページ](//images.ctfassets.net/pppgbgujcovf/6vEHq17BEka7LAC3iBT5vl/214f347a4ac5669b0fc0a288eb4e1dae/next-js.png)
:img-caption{text="Next.jsのトップページ"}

[Next.js]の開発ドキュメントは「まずチュートリアルを読んでね」というメッセージがいろんなところから伝わり、サイトの目的が明確なところが参考になります。

初学者にひとつ目の成功体験を達成してもらうことが今後の利用につながるので、実利にかなった目的だといえます。

コンテンツもチュートリアルとドキュメント、APIリファレンスが分かれていて、開発者の習熟度に応じて見るべきコンテンツがわかりやすいところもポイントです。

### 2. Nuxt

![Nuxtのトップページ](//images.ctfassets.net/pppgbgujcovf/1KJj4ojllQawQsVr7ZqBfY/d32c2f653d0a82904fa982909fd7096f/nuxt.png)
:img-caption{text="Nuxtのトップページ"}

[Nuxt]の開発ドキュメントはコンテンツの種類が豊富で、デザインもきれいです。ドキュメントやチュートリアルの他に、ショーケースやユースケースごとの実装例もあります。

プラットフォームごとへのデプロイの方法や、モジュールへのリンク集もまとめてあります。

Nuxtのサイトは英語・日本語・フランス語の3カ国語で利用できます。多言語対応をしているサイトなら、この点も参考になりそうです。

### 3. Stripe

![Stripeのトップページ](//images.ctfassets.net/pppgbgujcovf/5RUR3XsvsaCfayU62qotrJ/717bae5de86bdaf91a61d601c2c0fe3d/stripe.png)
:img-caption{text="Stripeのトップページ"}

[Stripe]の開発ドキュメントは、図を用いてフローなどをわかりやすく説明しているところが参考になります。Stripeは開発者にとって理解が難しい製品ではありますが、ツールチップなどを用いた「わかりやすさへの工夫」が読み取れます。

デザインもきれいで、製品が多い場合のサイト設計に役立ちそうです。その他に、[Stripe Payment Element](https://stripe.com/docs/payments/payment-element)のように、機能をウェブ上で体験できるプレイグラウンドもあります。

### 4. Contentful

![Contentfulのトップページ](//images.ctfassets.net/pppgbgujcovf/7ipnNF1rLslMwO8SJ1ojgf/deff46acb3dc0dacf7c3b42025d840a6/contentful.png)
:img-caption{text="Contentfulのトップページ"}

[Contentful]は「Concepts」として、各コンテンツにおける共通の概念を初めに提示しています。例えばAPIの全体像やドメインモデルなどがConceptsで紹介されています。

ナビゲーションもわかりやすく、ページの上部には各コンテンツへのリンクがあり、どのページを読んでいても共通しています。

JavaScriptやRubyなど、言語・プラットフォームごとの使い方についてもまとめてあり、開発者の課題を解決する工夫が見てとれます。

### 5. Terraform

![Terraformのトップページ](//images.ctfassets.net/pppgbgujcovf/7b90IjLfiT8GCpC6B2PKez/a618009858ca3de821086b8a8c1fc41b/terraform.png)
:img-caption{text="Terraformのトップページ"}

[Terraform]というよりHashicorp製品について全体的にいえるのですが、チュートリアルがとても充実しています。[Hashicorp Learn](https://learn.hashicorp.com)というサイトがあり、初学者向けにコンテンツを提供しています。

例えば「[Terraformを利用してAWSにインフラを構築する方法](https://learn.hashicorp.com/tutorials/terraform/aws-build?in=terraform/aws-get-started)」といったコンテンツがチュートリアル形式で公開されています。

## 参考になるサイトから得た学び

前述した5つのサイトを通して、次のような学びを得ました。

* 初学者向けにチュートリアルを提供している。また、チュートリアルへの導線が明確になっている
* 習熟度に応じて「チュートリアル・ドキュメント・APIリファレンス」とコンテンツが分けられている
* ショーケースで採用事例を提示している
* ユースケースごとの実装例を提供している
* 用語の概要をツールチップで表示したり、プレイグラウンドを用意するなどの工夫がある

## おわりに

開発ドキュメントを書くときの参考になるサイトを5つ紹介しました。その中で、チュートリアルの提供など、分かりやすいサイトにはいくつか共通する項目があるという学びがありました。

よりよい開発ドキュメントを書く上での参考になればうれしいです。

[Next.js]: https://nextjs.org
[Nuxt]: https://nuxtjs.org
[Stripe]: https://stripe.com/jp
[Contentful]: https://www.contentful.com
[Terraform]: https://www.terraform.io

「わかりやすい開発ドキュメントにはどんなコンテンツが必要なのか」「レイアウトはどうするべきか」など、コンテンツについて考える上で参考になるサイトを調べたので、この記事でまとめています。

開発ドキュメントを書くときの参考になるサイト5選

私はテクニカルライターとして開発者向けのドキュメントを書く仕事をしています。自分の仕事について説明することがあるのですが、頭の中を整理するために「テクニカルライティングとは何か？」についてまとめてみます。

この記事ではテクニカルライティングとは何か、必要性などについて、例を用いながら整理します。この記事を読むことで、テクニカルライティングについて学ぶ準備ができればと思います。

::author

#### 目次

## テクニカルライティングとは何か

![取扱説明書の例](//images.ctfassets.net/pppgbgujcovf/6ntmGEdFkj7pFmtrcDCbeJ/911f54d05ac28ce3ba1afcd21f9ba6ad/_____________________.jpg)
:img-caption{text="取扱説明書のイメージ"}

テクニカルライティングとは、私は「ある製品について、利用者にわかりやすく伝えること」だと考えています。ここでいう製品とは電子レンジのような家電製品や、開発者向けのドキュメントなどがあります。

三菱電機『[生産性が向上する「テクニカルライティング」とは](http://www.mitsubishielectric.co.jp/meltopia/specialfocus/case11.html)』では、テクニカルライティングについて次のように説明しています。

> テクニカルライティングは、技術的な内容を目的や読み手に合わせて分かりやすく伝える手法です。

例えば家電製品について、文章やイラストなどを用いて利用者にわかりやすく伝えることがテクニカルライティングだといえます。

広義の意味では、全般的な文章作成術、例えば論文や提案書を書く手法をテクニカルライティングという場合もあります。ただ、この記事では前述した意味で用います。

## テクニカルライティングの例

テクニカルライティングの例としては、例えば家電製品の取扱説明書やプログラミング言語・フレームワークなどのドキュメント、技術者が書く技術ブログなどがあります。

ここでひとつ、電子レンジを例にあげてみます。

前章でテクニカルライティングについて「ある製品について、利用者にわかりやすく伝えること」だと述べました。製品について書く上で、この定義にいたるまでには次の三段階があると考えています。

| 段階 | 概要 | 例 |
| :---: | --- | --- |
| 1 | ある製品について書く | 食品に含まれる水分子を2.4GHzのマイクロ波で振動させることで加熱します |
| 2 | ある製品について伝える | 食品に電波を当てることで加熱を行います |
| 3 | ある製品について利用者にわかりやすく伝える | スタートボタンを押すと食べものが温まります |

段階1の例はTDK Techno Magazine『[電子レンジの仕組みとは？加熱の原理や基本構造を解説](https://www.tdk.com/ja/tech-mag/hatena/032)』より引用しました。この三つの中で、電子レンジの取扱説明書という前提では、私たち多くの利用者が知りたいことは段階3の例だと思います。

このように、単なる事実ではなく「利用者にとってわかりやすいことばで必要なことを伝える」のがテクニカルライティングだといえます。

## なぜテクニカルライティングが必要か

テクニカルライティングとは「ある製品について利用者にわかりやすく伝えること」だと述べました。また、電子レンジの取扱説明書を例に紹介しました。

では、もしテクニカルライティングを行わなければ、電子レンジの取扱説明書はどうなってしまうのでしょうか。

### テクニカルライティングをしない場合

![電子レンジの例](//images.ctfassets.net/pppgbgujcovf/nasZTiS4bjsx37VF0ZyHz/554b0a7b676d153ca7d34f8ef7c3f27e/________________________.jpg)
:img-caption{text="電子レンジのイメージ"}

電子レンジの例でいうと、取扱説明書がわかりづらかったら、利用者はあれこれ試しながら電子レンジを使うかもしれません。もしかしたら危険な使い方をする可能性だってあります。

そもそも使い方がわからないと買ってくれない、ということも想定できます。このように、取扱説明書ひとつで製品の使われ方や売上が大きく変わってしまう可能性があります。

### 開発者が取扱説明書を書く場合

では、取扱説明書は書きさえすればいいのでしょうか。もちろんそんなことはありません。

例えば、電子レンジの開発者が取扱説明書を書くとします。開発者は開発のプロではありますが、文章のプロではありません。一文が長かったり、利用者がわからない用語を使ったりするかもしれません。

事実は書いているけどわかりづらい、というような取扱説明書ができあがることになりそうです。

### テクニカルライターの役割

開発のプロがいるように、文章のプロもいます。これがテクニカルライターです。表にまとめると、開発者・テクニカルライターの役割はそれぞれ次のようになります。

| 職種 | 役割 |
| --- | --- |
| 開発者 | 利用者が使いやすい製品を開発する |
| テクニカルライター | 製品について利用者にわかりやすく伝える |

テクニカルライターは、開発者などとコミュニケーションを取りながら、利用者にとってわかりやすく伝わる文章を書いていきます。より利用者に満足してもらえ、結果として製品としての価値がさらに高まります。

近年ウェブサービス関連の企業がテクニカルライターの採用を進めていますが、背景にはこういった理由があると思っています。

## テクニカルライターに必要なスキル

前章で述べたように、テクニカルライターは文章を書くことだけが仕事ではありません。文章はもちろん、製品に対する技術的な理解、開発者など関係者とのコミュニケーションも重要なスキルになってきます。

つまり、テクニカルライターには次の三つのスキルが必要になってきます。

1. 文章力
2. 技術力
3. コミュニケーション力

取扱説明書やドキュメントなどの文章を書くことが決まってから、文章が世の中に公開されるまで、そのすべてに携わるのがテクニカルライターの仕事だといえます。もちろんこれは組織によって異なると思いますが、大きな違いはないと考えています。

製品を理解し、利用者を理解し、利用者にとってわかりやすい形で製品について伝えます。中には「そもそも紙でいいのか」という「伝える媒体」に対する検討も行うこともあるかもしれません。

テクニカルライティングは上記三つのスキルを最大限活用した総合格闘技のようなものだといえそうです。

## おわりに

テクニカルライティングとは「ある製品について、利用者にわかりやすく伝えること」だと述べました。また、テクニカルライティングの例として電子レンジの取扱説明書を紹介しました。

テクニカルライティングは文章を書く以外にも技術、コミュニケーションといったスキルが重要になってきます。以上がテクニカルライティングの概要になります。

最後に紹介になりますが、テクニカルライティングのスキルを身につける方法としては技術ブログを書くことをおすすめしています。このブログで[技術ブログ入門](/guides/tech-blog)というコンテンツも公開していますので、あわせてご覧ください。

この記事ではテクニカルライティングとは何か、必要性などについて、例を用いながら整理します。この記事を読むことで、テクニカルライティングについて学ぶ準備ができればと思います。

テクニカルライティング

3級テクニカルライティング試験の概要や勉強方法など

エンジニアがテクニカルライティングのスキルを高める方法

開発ドキュメントを公開するまでの基本的な7つの手順

開発ドキュメントを公開したときにやる3つのこと

開発ドキュメントの変更要求のときに集めるべき6つの情報

テクニカルライターにとって重要な3つのスキル

開発ドキュメントをレビューする方法

開発ドキュメントの文章を推敲する方法

開発ドキュメントの書き方。意識したい9つのこと【技術編】

開発ドキュメントの文章における表現方法【箇条書き・表など】

開発ドキュメントの文章を自動で校正する方法【textlint】

開発ドキュメントにおけるアウトラインの書き方

開発ドキュメントの要件を整理する方法

開発ドキュメントを書く前に決めるべき3つのこと【企画編】

開発ドキュメントサイトにおけるコンテンツの種類まとめ

開発ドキュメントを書くときの参考になるサイト5選

テクニカルライティングとは何か、なぜ必要かを例をもとに整理します

テキストエディタ入門: Visual Studio Codeの使い方〈VSCode〉

技術ブログ入門: エンジニアのための技術系ブログの始め方

エンジニア転職で利用したいサイト・エージェント7つ【無料相談あり】

【エンジニア】副業するなら登録しておきたいサイト・エージェント5つ

プログラミングスクールで選びたいおすすめ6つ【効率的に学べる】

テクニカルライティング

3級 テクニカルライティング試験の概要や勉強方法など

エンジニアがテクニカルライティングのスキルを高める方法

開発ドキュメントを公開するまでの基本的な7つの手順

開発ドキュメントを公開したときにやる3つのこと

開発ドキュメントの変更要求のときに集めるべき6つの情報

テクニカルライターにとって重要な3つのスキル

開発ドキュメントをレビューする方法

開発ドキュメントの文章を推敲する方法

開発ドキュメントの書き方。意識したい9つのこと【技術編】

開発ドキュメントの文章における表現方法【箇条書き・表など】

開発ドキュメントの文章を自動で校正する方法【textlint】

開発ドキュメントにおけるアウトラインの書き方

開発ドキュメントの要件を整理する方法

開発ドキュメントを書く前に決めるべき3つのこと【企画編】

開発ドキュメントサイトにおけるコンテンツの種類まとめ

開発ドキュメントを書くときの参考になるサイト5選

テクニカルライティングとは何か、なぜ必要かを例をもとに整理します

テキストエディタ入門: Visual Studio Codeの使い方〈VSCode〉

技術ブログ入門: エンジニアのための技術系ブログの始め方

エンジニア転職で利用したいサイト・エージェント7つ【無料相談あり】

【エンジニア】副業するなら登録しておきたいサイト・エージェント5つ

プログラミングスクールで選びたいおすすめ6つ【効率的に学べる】

3級テクニカルライティング試験の概要や勉強方法など