働き方

エンジニアでもドキュメントは書けるようにしておくべき

エンジニアにとってドキュメントを書くのは、楽しい仕事ではありませんが、避けては通れない仕事でもあります。

ドキュメント作成は簡単なようで、実は意外と難しい仕事でもあります。今回は、エンジニア目線からドキュメント作成という仕事とその方法を説明します。

この記事が役に立つ人

エンジニアでドキュメントを作りが苦手な人

エンジニアとドキュメント

エンジニアの中には、技術力はすごいのにドキュメントはいまいちという人がいます。また、新卒にドキュメントを頼んだ場合は、たいてい低品質のものが出来上がってきます。

これは仕方がないことです。ドキュメントの作成には、ちゃんとした方法論があり、これを知らないことには確かなものはできあがりません。

ドキュメントを軽視するエンジニアも多いですが、チームで仕事を効率よく進めるためにも、エンジニアのマナーとしてもドキュメントは作成出来るようにしておくべきです。

エンジニアがドキュメントを書くとき

エンジニアはあまりドキュメントを書く機会がない職業です。

書いたとしても、パワーポイントやExcelで図が中心の設計図や構成図を作るか、自分や技術者向けのテキストベースの資料をマークダウンやWikiでサクッと書く程度です。

しかし、ふいに納品物としてのお堅い仕様書や、ユーザ向けのマニュアルを作ったりしないといけない機会が訪れます。

この時のドキュメントの品質が低いと、いくら技術力が高くても少し残念なエンジニアになってしまいます。

あまり楽しい仕事ではありませんが、避けては通れないので、エンジニアといえど一般的なドキュメント作成能力は必要になります。ドキュメント作成能力をウリにする必要はありませんが、最低限こなせるようにはしておきましょう。

ドキュメントは質よりスピード

ドキュメント作成は、品質を求めればキリがありません。書き直しが発生がすることもよくありますので、あまり完璧なものを求めすぎない方が良いです。80%ぐらいの品質を目指し、質よりスピードを重視すべきです。

たまにレビューで誤字脱字を見つけることに命を賭ける人がいますが、間違ってもこのようにならないようにしましょう。本質から外れています。

ドキュメントの書き方


では、エンジニアのドキュメントの書き方について説明します。

基本はwordを使用する

ドキュメントのアウトプットの最終形はPDFが基本です。では、PDF出力する元は何で作るのか言うと、特殊な事情がなければ、基本は Word を使うべきです。それほど重量のない簡易資料ならテキストエディタでマークダウンで書いてそれをPDF出力してもOKです。

Excel方眼紙でページフォーマットを作成して、ページを量産していくのはやめましょう。Escel方眼紙でドキュメント作成は、時間がかかるうえに後からの修正もしずらく、印刷時の見栄えも悪く、百害あって一利なしです。指定がある場合なら仕方がありませんが、間違っても自分から進んで作成してはいけません。

Wordで見出しと箇条書きのレベルを意識するだけで、それなりの綺麗なドキュメントを作ることができます。

まずは目次を完成させる

ドキュメントを作るには、まず目次を作るところからはじめましょう。

目次といえどあなどるなかれ、ちゃんとしたものをつくるとなると時間もかかりますし頭も使います。

どういった内容をどれぐらいの量で書くのか、各章(セクション)の内容と見出しレベルを意識して、見栄えのいい目次を作りましょう。

いい目次ができないと、中身がちゃんとしたドキュメントはできません。

技術用語は大文字小文字の区別を意識する

技術用語の大文字、小文字は正しく使うべきです。ここを間違っていると、いまいちな技術者と見なされます。

例えば、Java だと JAVAjava はNGです。わかりずらいところだと、curl はNG、cURL の表記が正しいです。

技術用語の正確な表記は普段から意識しておきたいところです。

一般的でない用語の初登場は注釈をつける

一般的でないない社内用語などは、ドキュメントで初登場時は注釈をつけるべきです。

例えそれが関係者全員にとって周知の事実であっても、それがドキュメント作成のルールです。

まとめ

以上、エンジニアにとってのドキュメントのあり方と、ドキュメントの作り方についてでした。

ドキュメントはめったに作成する機会はありませんが、できるようにしておくべきです。食わず嫌いはやめて、最低限の知識はもっておきましょう!

ABOUT ME
tara
tara
年収360万円でIT業界のキャリアスタート
SES -> Web業界 -> 大手メーカー -> フリーランス
と経験してきて、現在は年収1000万円を越えました。

エンジニアのキャリアアップに役立つ情報を発信していきます。