ドキュメントを書き終わるまでが開発作業です

小学校から国語の勉強をしてきたはずなのに、今頃になって文章の書き方をマスターした、ユゲタです。 開発ドキュメント、本当にめんどくさいですよね。 エンジニアの方でプログラミングは好きだけど、ドキュメントを書くのはめちゃくちゃ苦手とか、純粋に嫌いという人も多いのではないでしょうか？ もちろん、全てのエンジニアがドキュメントが苦手というわけではないと思いますが、ドキュメントって開発とセットで行う事を色々な意味で説明してみたいと思います。 「ドキュメントが苦手」とか「うちの会社はドキュメントは後回し」と考えている人は是非、このブログを読んでみてください。

プログラミングスキルを上げたかったら、ドキュメントを書きなさい

プログラミング初心者だけでなく、実際に仕事しているエンジニアも、どこまでスキルが高くなっても、もっともっとスキルをアップさせたいと考えます。 そしてこれは、どのレベルの人に対しても言えますが、スキルアップしたいのであれば、まずはドキュメントを書く事をオススメします。 プログラミングを書いてスキルを上げる人がほとんどですが、それをドキュメントにまとめている人は、そうそういません。 ここがエンジニアリングをスキルアップさせる手段が人によってまちまちである原因のひとつでもあります。 同じように学習する事が多い受験勉強などは、かなり工程化されていて、日々のスケジュールもかっちり年単位で組まれていて、習得していくのに対して、 プログラミングは、スクールはあるけれど、９割以上の人が挫折して、多くの人が口を揃えて「ITは難しい」と言う。 まるで、プログラミングは、魔法使いの術のような見方をしていたり、この世の未知の領域のように考えてしまっているようです。 「かんたんにできるプログラミング」的な書籍もたくさん販売されていますが、これを是非、学校で勉強していた時のように、学習をパソコンに記録するのではなく、 紙のノートに記載してみると、プログラミングって、めちゃくちゃ効率的に学習できるようになります。 パソコンのメモ帳などでも、同じかと思いますが、学校の時にパソコンでノートを取る事を想像するよりも手書きでノートに書き殴った方が効率的と思いませんか？ それと同じで、手書きノートを作ると、ITスキルアップはかなり安定的に効率的にできるという事は、スクールでも教えていない技です。

仕事を効率的にしたかったら、ドキュメントを書きなさい

20代の頃は一生懸命プログラミングを勉強して、30代になって、まあまあ思った通りに作りたいものが作れるスキルが身について、ようやくこれから自分の何かプログラミング作品を作りたいと思った時に、 会社のマネジメントを任されて、プログラミングから離れてしまう中間管理職エンジニアが、なんと多い事でしょう。 多くの会社のCTOと話をすると、みんな最初に必ず「今はプログラミング書いてないんですけどね」と言います。 別にそれはそれでもいいんですが、実はプログラミング書きたいのに書けないと言う人は、仕事における効率を良くするために、ドキュメント文化を社内に構築するマネジメントをする事をお勧めします。 でも、これまでドキュメントは二の次思考でやってきた人は、ドキュメントって、どのように書けばいいのか？何を書けばいいのか？どんな粒度で書けばいいのか？ と言う事がわからないと言います。 でも、ドキュメントが無い仕事現場というのは、本当に効率が悪く、口伝えの伝言ゲームで作業が進められて、結果的に作業が完了したら、「なんかちょっと違う」みたいな繰り返しで、 とにかく１週間で終わる仕事が1ヶ月以上もかかるというのが当たり前になっています。 一度、しっかりと、あらゆる事をドキュメント化してみると、本当に効率的を体感できるので、是非気持ちを切り替えてみましょう。

他人が見て理解しやすい、ドキュメントを書きなさい

最後に、ドキュメントの書き方ですが、これは書籍を書く人であれば、誰でも意識している「読む人」が読んだ時に、問題なく読める（読みやすい）事をゴールにするのが一般的です。 エンジニアにドキュメントを書かせると、その後意味のわからない内容が書かれている箇所を「これ何？」と質問しても「何でしょうね？」と自分が書いたことの意味すらわかっていないケースが非常に多いです。 そもそも、単語の使い方に関しても、「エンジニアならこれぐらい知ってるっしょ」的なノリで書くためにスラングも含めて、その社内の古株でしかわからないドキュメントになりがちです。 また、最悪なケースとして、サンプルなどが記述されていても、書いた人のhostsに記述されているようなローカルの任意アドレスで記述されてしまうと、その後誰も何も確認ができなくなってしまうことは当たり前だし、 その環境外で見る事が想定できていない書き方をしてしまうと、ドキュメントが意味のないものになってしまいます。 意味のないドキュメントは「ゴミ」でしかありませんからね。 ゴミを一生懸命作るよりも、仕事の効率が良くなるドキュメントを、時間をかけて作った方が、作る本人もよほど価値を感じると思います。 少し厳しい言い方をしてしまいましたが、SDGs的にも、「ゴミ撲滅推奨」をしているユゲタでした。