見出し画像

プログラマ脳とドキュメンテーションについて考えた

jnkykn

こんにちは。サイボウズ株式会社 開発本部 People Experienceチームの貴島(@jnkykn)です。全国的には、まだまだ暑い日があるようですが、北海道はスタッドレスタイヤや除雪機のCMも始まり、すっかり秋めいています。カバーは、色づき始めている近所のイチョウ並木です。今日、やっとNetflixの三体シーズン１を見終わりました。原作からアレンジされた部分もありますが、この続きが待ち遠しいです。さて、先週はコネクト支援業務ネタがたくさんあったのですが、今日は積読消化Dayとして、最近読んだ本をご紹介します。

エンジニアが一生困らないドキュメント作成の基本

物理本が届いてすぐに、一気に読みました。ドキュメントの書き方だけでなく読み方の解説もあり、ページを追うごとに「そうか！そうだったんだ！」と霧が晴れていく感覚がありました。文章の書き方とプログラミングの共通点など、エンジニアに理解しやすい比喩がありがたく「読み手を意識した文章」のお手本とも言えると思いました。おそらく、ドキュメンテーションで苦労しているエンジニアの多くは、ウォーターフォール型の大規模システム開発担当者だろうと想像しているのですが、そんなウォーターフォール型開発のドキュメントの構成やポイントにも言及されているところが「さすがだな！」と思いました。
現在は技術広報的なことをやっている私ですが、長年システム開発に携わっていました。そして、ドキュメント作成は得意な方だという自覚がありました。採用面接で「プログラマですが、ドキュメント作成は得意です」と言ったらテクニカルライティング担当になったという謎の経歴もあります。ドキュメントは、人に何かを伝えるものであり、プログラムは機械に指示を与えるものです。誤解を恐れずに書くなら、機械に指示を与える場合どんな書き方であれ最終的に目的が達成できる記述ができていればOKです。（実際には、同じプロジェクトのメンバーや引き継ぎ先のメンバーにわかりやすいコードが望ましい）一方人が相手の場合は、相手の知識や感情、興味など、様々な影響があり、仕様書に書いていても実装で間違いが発生したりします。そこが、ドキュメンテーションの難しさだと思います。本書で、その難しさに対処するための考え方や方法を知ることができると思うので、おすすめです。

プログラマー脳

エンジニア職から離れた今、優れたプログラマーになるための本を読むのに意味があるのか？と、気になりつつも積読状態になっていた一冊です。認知科学に基づくアプローチという副題にあるとおり、プログラムコードを読むとき書くときの脳の働きを、短期記憶、長期記憶、ワーキングメモリの働きをもとに解説されています。確かに、自分を含めて、頭の中で何が起きているか？は無視できないなと、納得できました。個人開発だけでなく、チーム開発でも、記憶のメカニズムについて理解して取り組むことは役立ちそうです。更に、オンボーディングについても、最後に独立した章としてページが割かれています。プログラミングのための新ピアジェ主義モデルは、参考にできそうだと思いました。
私が勤務してきたシステム開発系の企業では、学生時代にプログラミングについて専門の教育を受けていないメンバーは少なくありませんでした。そして、文系理系関係なく、優秀なシステム開発者が多数いました。そんな経験から私は、「英語でも日本語でも良いから、機能を記述できればプログラミングはできる」と、主張してきました。頭の中に処理の構造や手順のイメージが無いままコードは書けないので、これは当然のことです。私は、すでに始まっている開発プロジェクトに途中参入する機会が多く（いわゆる火消し役）他人が書いたコードを読むことが欠かせませんでした。世の中で働くプログラマの多くは、似たような経験をお持ちなのではないでしょうか？そんな環境で、プログラムコードの読解力が鍛えられたと言っても良いと思います。経験から身につけられるものは個人の資質やその機会に恵まれるかどうか？に依ることも多いので、プログラムコードを読む認知科学的なテクニックがわかっていれば、初学者の学習効率が上がりそうです。先週参加した「JavaDoでしょう#26【札幌 9/28】アンカンファンレンスをやってみよう&軽く交流会」で、コードにコメントを書く書かない問題について話したとき、共同作業の認知負荷を下げるための工夫が必要なのでは？という話をしたのを思い出しました。

まとめ

今日は、ドキュメント作成とプログラミングに関する本を読んだのですが、どちらも人が読むことを考えることがポイントだなと、腹落ちする内容でした。脳内で何が起こっているか？は、興味深く、プログラマ脳で紹介されているモデルや演習は、掘り下げていきたいと思いました。

おまけ

西原(@tomio2480)さんの退職宣言が出ましたが、当面Developer Councource Unitとしての活動はやっていきますし、コミュニティ活動は会社関係なく継続すると思うので、よろしくお願いします。

ちなみに私は、次の行き先が決まってから退職願いを提出する派です。

この記事が気に入ったらサポートをしてみませんか？