QAチームのいさな(@isanasan_)です。今回は筆者が実践しているセルフドキュメンテーションと、おすすめmarkdownノートアプリのobsidianを紹介します。
モチベーション
lancersではリモートワーク化が進んでおり、開発業務に関してはほぼリモートで簡潔する形になっています。
かくいう筆者も大阪からフルリモートで業務させて頂いてます。
ところで、本社オフィスも持たず、全世界でリモートワークを展開するGitLabが上場したニュースが先月話題になりました。
また、GitLabのプラクティスに倣い、リモートワークにおけるドキュメンテーションの重要性を説く記事も注目されました。
ことほど左様にリモートワーク下において質の高いドキュメントを維持管理することは組織のスケールアップにとって重要であるというのは異論ないかと思います。
とは言うものの、ドキュメンテーションも一つのスキルであり、求められていきなり高品質なものをアウトプットできるかというとそうではないのが難しいところです。そこで、筆者が以前から取り組んでいるプラクティス、セルフドキュメンテーションとおすすめツールobsidianを紹介しようと思います。
セルフドキュメンテーションとは
日本語にすると「自己文書化」、なんだか仰々しいですが、つまるところある種の日記です。
セルフドキュメンテーションを行う目的としては以下の3点です。
- ドキュメンテーション能力を鍛える
- 日々の学びをより深いものにする
- アウトプットを効率良く行えるようにする
また、一般的な日記やメモと比べた特徴として下記の3点が上げられます。
- ファイルの最小単位を日別とする
- 全ての出来事を記録する
- 定期的に振り返りを行い清書する
それぞれ見ていきましょう。
ファイルの最小単位を日別とする
毎日新規のmarkdownファイルを作成して、そこに記録をつけていきます。これをデイリーノートと呼ぶことにします。日を跨いだら問答無用で新規のファイルを作成して、そちらに続きを記載していきます。
筆者は元々飽き症で、だいたいのことは三日坊主になる性分なのですが、極力文書化を習慣付けしやすいように最小単位を日別とすることにしました。この時点ではただの日記なのですが、続いてみていきましょう。
全ての出来事を記録する
毎日、デイリーノートにやったことや遭遇した出来事、その時の考えをひたすら書いていきます。例えば、何らかの実装作業をしていてよくわからないエラーに遭遇したら、エラーメッセージをそのまま貼りつけておきます。試したことやググってヒットした記事などもそのまま記録します。もちろん、最終的に解決したら解決方法を書いておきます。この時、文章としての体裁を整える必要はなく、ただの記録としての記載に留めます。加えて、極力記載内容についてのカテゴライズをしないという点も気をつけています。
このように「記録として残すべきことなのだろうか？」とか「これは何についての何なのか？」といったことを考えるのを一旦やめ、ただ書くことを目的とすることでドキュメンテーション行為に対する心理的ハードルをかなり下げることが出来ます。
定期的に振り返りを行い清書する
この時点で手元に残っているのは単なる日々の記録に過ぎません。定期的に振り返りを行い、ここではじめて記録した内容のカテゴライズをします。ある程度まとまった情報(感覚的には1000字程度)が手に入ったら、記録した内容を元にドキュメントとして清書します。清書したものはブログとしてアウトプットするなり社内のwikiに投げるなりします。
obsidianの紹介
ここまで読んで、「いや、無理では？」と思われた方が多いのではないでしょうか。そこで、筆者が愛用しているセルフドキュメンテーションに最適なmarkdownノートアプリobsidianを紹介します。
obsidianとは
いわゆる、markdownエディタです。コンセプトとして掲げられているメッセージはこちら↓
A second brain, for you, forever.
windows, mac, Linuxで無料で利用することが出来ます。
ここからはobsidianを使ってセルフドキュメンテーションを行いながらどんな感じのツールなのかを紹介していきたいと思います。
デイリーノートを作る
早速デイリーノートを作成して記録していきましょう。デフォルトのキーバインドであればAlt-tでテンプレートを適応した新規ページを作成できます。
ここに今日の出来事をとにかく書いていきます。今日は丁度、コードレビューをしていた時にphpstan関連でいろいろあったのでそのことについてありのまま書き込みました。
デイリーノートにリンクを貼って振り返る
次に振り返りをします。今月はphpstanについて色々あった気がするので、直近のphpstanという単語を含んだファイルを開き、下記の手順でノート同士をリンクするページを作成します。
- 対象の単語を
[[]]で囲う ctrlを押しながら1で囲んだ単語をクリックする
するとphpstanという名前のファイルが新規作成されました。
作成されたphpstanという名前のファイルを開くと、右側のペインにphpstanという単語を含んだファイルと、単語の場所へのリンクが表示されています。
そして下記の手順でリンク先の情報をまとめることが出来ます。
- 右側のペインから対象のリンクをドラッグ&ドロップ
- リンクに
#を追記し見出しを選択 - 先頭に
!を追記
このように、obsidianを使って簡単にデイリーノートの作成から振り返りまでを行うことが出来ました。あとは知見が貯ってきた頃合いを見計らって、ドキュメントを清書すればいとも簡単にドキュメントをアウトプットすることが出来ます。
まとめ
ソフトウェアの世界は日々、技術の複雑化&高度化が進んでおり、ITエンジニアには高い専門性が求められます。それに加えてリモートワークの浸透により非同期コミュニケーション、ドキュメンテーションのスキルの重要性も増してきています。みなさんも是非セルフドキュメンテーションとobsidianを試してみてください。
参考
クリアファイル整理法
Scrapboxは情報整理ツールではない
Obsidianは最高のマークダウン『メモ』アプリである