テキストエディタはエンジニアが一生使う大切な仕事道具です。プログラミングを始めるなら、まずエディタの使い方を学びましょう。ここでは代表的なエディタである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つ【効率的に学べる】

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

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

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

::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)というコンテンツも公開していますので、あわせてご覧ください。

この記事ではテクニカルライティングとは何か、必要性などについて、例を用いながら整理します。この記事を読むことで、テクニカルライティングについて学ぶ準備ができればと思います。

テクニカルライティング