文書作成とプログラミングに共通する課題

背景

私の会社では GitHub を使って開発を行なっています。改善すべきところを見つけたら Issue を作って対応する。1年以上も続けていることなのに、Issue の書き方がよくないため、上長に余計なコストをかけてしまっていました。

そのとき CTO に勧められたのが「 SE のための図解の技術、文章の技術 」という本です。この本を読んで、私が作成した Issue が読み手に伝わりにくい原因を知ることができました。さらに、プログラミングスキルが伸び悩んでいる原因にも共通する部分があることに気づきました。

私が感じた「文書作成」と「プログラミング」の共通点についてまとめようと思います。

伝わりやすい文書を書くためには、実際に書き始める前に文書の「構成」を考えなければならないと書かれていました。その構成を考える際に、文書全体を階層構造にしておくことで、読みやすく、理解しやすい文書を作成できるということです。

私は Issue 作成に限らず、日報やドキュメントを書くときも、構成を全く考えずに書いていることに気がつきました。書いている途中で何を書いているのか分からなくなることが多いです。

これはプログラミングでも同じだなと、本を読んでいて気がつきました。

私は仕様がある程度固まってくると、まだあまり整理できていないのに、すぐにプログラムを書き始めます。すると文書作成と同様、書いている途中で何を実装しているのか分からなくなります。

また、しっかり仕様を整理したわけではないので、仕様の考慮漏れがあるなどして、手戻りが発生してしまっています。

文書作成にしても、プログラミングにしても、全体を階層構造にすることで複雑な事柄を細分化し、簡潔にまとめることが大切だと感じました。

読み手が理解しやすい文章を書くには、長い歴史を経て作り上げられたパターンを使うことが勧められていました。

例えば、「序論ー本論ー結論」や「起承転結」という展開パターンです。

長い歴史から確立されたこのパターンは、人間が順を追って事象を把握、理解する際の思考の流れに合ったものであり、理解の仕組みを反映したもの考えられています。

つまり、このパターンの沿って書けば、自然と読み手が理解しやすい文章をかけるということです。

これはプログラミングでも同じだなと思いました。

例えば、私が使用しているオブジェクト指向言語にも、デザインパターンと呼ばれるパターンがあります。

これも上記と同様に私よりもはるかに優れたエンジニアたちが長い歴史を経て確立した設計パターンです。システム設計で困った時に、デザインパターンを使うことで解決する問題も多いでしょう。

文書作成にしても、プログラミングにしても、すでに確立されているパターンを使うことで、目標を達成しやすくなるということです。巨人の肩の上に立つというのは本当に大切だなと再確認しました。

文書作成で抱えていた課題とプログラミングスキルの伸び悩みの原因に共通する部分があったことに驚きました。

今回の学びは汎用的なもので、他にも活かせる部分があるはずです。一つの学びをより広い範囲で活用できるようになりたいものです。