作業と一緒にドキュメントを残すコツ

はじめに

趣味であれ、仕事であれ作業をしているとシステムを動かすためにその場しのぎをすることがあると思います。
そして、その場しのぎが一生に一度ぐらいの頻度ならいいのですがおのずと2回,3回と訪れると思います。
そこで、作業をしながらドキュメントを残せば・・・と考えるのですが面倒ですよね。。
そんな方への処方箋(自分要)として書き残します。

ひな形&書く内容

ひな形はmarkdownで残します。

# 概要(背景・目的)
# 関連資料
# (任意)作業概要
# 作業詳細

見出し	書く内容
概要(背景・目的)	できないことと、やりたいことを明記する
関連資料	調べて使えそうな部分が乗ってそうなら記載する
(任意)作業概要	システムフローの記述が必要なら書く(設計レベルで手順を書く必要があるなら記載)
作業詳細	やったことを書く(NGも他の事例で検索にヒットして役に立つ場合があるため残すと吉、清書する際はOKを先に持ってくると読み手に優しい)

例示

ここでは例示を示します。
（例はものすごく雑なので適宜読み替えてください）

概要

AWS CLIでS3が触れない。
aws s3 lsでバケット一覧を見たい

関連資料

• https://docs.aws.amazon.com/ja_jp/cli/latest/userguide/cli-chap-troubleshooting.html
  • デバックオプションが使えそう
• https://docs.aws.amazon.com/cli/latest/reference/sts/get-caller-identity.html
  • アクセスキーの疎通を見るため
• https://docs.aws.amazon.com/ja_jp/IAM/latest/UserGuide/id_credentials_temp.html
  • 一時的な認証を通して接続する方法がある

作業詳細

(OK) IAMに一時的な認証を通した

(やったことを記入～～～)

(NG) アクセスキーを作り直した

アクセスキーとシークレットは get-caller-identity で取れた違う
(やったことを記入～～～)

(NG)　・・・

(やったことを記入～～～)

さいごに

ドキュメントを書き残すと整理するは別の脳を使うため、作業中はあまりドキュメント整理に頭を使わず、上記のひな形で軽くまとめておくと後々幸せになると思います。
もちろん、解決するのが最も大事ですができない場合も相手に見せることでヒントをもらえたりするのでお得です。
ひな形の場所は任意ですが、github wiki, esa, notion, confluence, backlog等などwiki機能があり、みんなが見れる場所に残すとさらにGoodです。
あまり力を入れすぎずにドキュメントへ残していきましょう！