まともなドキュメントを書けるエンジニアは少ない




## 参考

https://pm.short-tips.info/culture/1217documentation.md

一部引用

以下は目次

- [ソフトウェア開発にドキュメントが必要な理由](https://pm.short-tips.info/culture/1217documentation.md#1)
- [開発者がドキュメントを書きたがらないわけ](https://pm.short-tips.info/culture/1217documentation.md#2)
- [開発者にとってのドキュメントを書く価値](https://pm.short-tips.info/culture/1217documentation.md#3)
  - [まともなドキュメントを書けるエンジニアは少ない](https://pm.short-tips.info/culture/1217documentation.md#4)
  - [ドキュメントを書くためにはスキルがいる](https://pm.short-tips.info/culture/1217documentation.md#5)
  - [テクニカルライターという職種がある](https://pm.short-tips.info/culture/1217documentation.md#6)
- [開発プロセスにとってのドキュメントを書く価値](https://pm.short-tips.info/culture/1217documentation.md#8)

## 開発者にとってのドキュメントを書く価値

### まともなドキュメントを書けるエンジニアは少ない

まず初めに、**まともなドキュメントを書けるエンジニアは少ないです**

Twitterから引用しますと、以下のような声が挙がってます。

<blockquote class="twitter-tweet"><p lang="ja" dir="ltr">ドキュメントを書けるエンジニア少ないのはすごく実感する。ドキュメントは開発をスケールさせることができる強力な武器なので、上手く活用するとエンジニア同士のコミュニケーションがなくなって開発効率上がるんだよね。伸ばすのが難しい能力 <a href="https://t.co/SgOrrPRcEF">https://t.co/SgOrrPRcEF</a></p>&mdash; pospome (@pospome) <a href="https://twitter.com/pospome/status/1539605902483144704?ref_src=twsrc%5Etfw">June 22, 2022</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>

<blockquote class="twitter-tweet"><p lang="ja" dir="ltr">「優秀なエンジニア」の定義、各種仕様を理解しててコードが書けるってのはもちろんだけど、何よりコードと同じくらいドキュメントが書けるってのはかなり大切なんちゃうかなぁ<br><br>ドキュメントがないコードなんてただのゴミだし、自分が仕上げた仕事をちゃんと他人に伝えきることまでできれば一流かと</p>&mdash; コミさん (@komi_edtr_1230) <a href="https://twitter.com/komi_edtr_1230/status/1252551047349850113?ref_src=twsrc%5Etfw">April 21, 2020</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>

ともすれば、「エンジニアはどんなプログラミング言語よりもまず日本語を読み書きできるようにするべきだ」という意見も。

エンジニアのコミュニケーション能力は度々話題に上がりますが、それは口頭だけでなく書面上でのやりとりを含むのかもしれません。

面接の場において、**XXプロジェクトでドキュメントを書きました！**と言えば少なくとも文章でのやりとりが可能なことの証明になりますね。

### ドキュメントを書くためにはスキルがいる

ドキュメントの作成にはツールを活用する会社があります。

例えば、javascriptのドキュメントの作成であれば、

- jsDoc

- doxygen

などのOSSライブラリーが活用できますよね。

あるいはソースコードとドキュメントが一体になったOSSライブラリも存在します（名前は忘れてしまいました...）

加えて、ドキュメントを書く際の文法も注意が必要です。
例えば、Markdownなどは書く際にどれだけ文法を深く知っているかで見栄えが変わります。

```md

##h2タグ

- 箇条書き

1. 箇条書き2

> 引用符

```

wikipediaのマークダウンの項目を見るとわかりますが、**以下全ての表記をマークダウンで表すにはそれなりの技量が必要になるのです。**

- 段落
- 改行
- テキストの強調
- コード
- リスト
- 見出し
- 引用
- リンク
- 水平線

https://ja.wikipedia.org/wiki/Markdown

これらのマークダウンを自由自在に操り思い通りの表現をすることは、開発者にとっても楽しい時間になるはずです。

### テクニカルライターという職種がある

Googleのソフトウェアエンジニアリングという本を読むまで知らなかったのですが、**テクニカルライターという職種がある**そうです。

参考になる方だと、こんなロールモデルがあります。

https://applis.io/posts/how-to-learn-technical-writing

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

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

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

また、こんな求人を見つけました。

```md
【テクニカルライター】プロダクトナレッジ共有ドキュメント作成の求人・案件

【仕事内容】
・現場のエンジニア、マーケター、営業とコミュニケーションを取り、
　プロダクトのナレッジ共有のための
　ドキュメント作成をしていただきます。
・資料ユーザーのフィードバックを元に
　ドキュメント内容の改善にも携わっていただきます。

【求めるスキル】
・テクニカルライターとしての経験5年以上
・プロダクト開発において複数部署と
　横断的にコミュニケーションを取った経験
・ソフトウェア開発においての基本的な知見
・ビジネスレベルの英語力

【歓迎スキル】
・システム開発のご経験
・GitHubのご使用経験
```

https://freelance.levtech.jp/project/detail/52919/?utm_campaign=google_jobs_apply&utm_source=google_jobs_apply&utm_medium=organic

レバテックのようなエンジニア専用サイトでは、**ドキュメント作成のプロ**というポジションでも需要があることが伺えますね。



## 参考：エンジニア組織の文化確立のための参考書籍

参考

<img src="http://www.hanmoto.com/bd/img/9784873119656_600.jpg">

参考：Googleのソフトウェアエンジニアリング

https://www.oreilly.co.jp/books/9784873119656/