SQUEEZEに転職してから頑張っていることの１つに「ドキュメントを書く」がある。
これはPyCon JPのスタッフをやっているなかで身についた習慣だと思う。PyCon JPの運営はボランティア活動でありスタッフメンバーも流動的なので、情報が属人的にならないためにドキュメントを書く文化が根付いてる。
僕はこのPythonicな文化がとても気に入っている。
エンジニア立ち居振舞い：ドキュメントを書く
ドキュメントを書くことによって得られるメリットは数多くあるけど、次のようなことを日々実感できている。
チーム
- 属人性を減らす
- 言った・言ってない議論をなくす
- ルールの明文化によって判断軸がぶれない
- ナレッジの共有
- 透明性の確保
個人
- 思考の整理
思考を整理するためのフレームワークとしての「書き言葉」の話は、naoyaさんの次のエントリーで詳しく言語化されてる。
書く行為には今自分で考えたことを文章という形で外部化し、それを足がかりに次の思考のステップへ進むということを強制する側面がありそれが大きいと思っている。つまり、書く行為は思考過程の不確実性みたいなものを最小限に留めながら物事を考えるフレームワークになっている。
とはいえ、ドキュメントに時間や労力もかけすぎてしまうのは避けなくてはならない。エンジニアは解決すべき課題に最も集中すべきだし、何事も頑張りすぎると人間は長続きしないので。
ドキュメントを楽して書くために普段意識していることはこんなところ。
- いつも使ってるエディタで書く
- コードと同様にバージョン管理する
- 必要最低限のドキュメントに抑える
- プログラムとドキュメントを乖離させない
- docstringやtestも立派なドキュメントと考える
