エンジニアのドキュメント作成で大事なことは何だろう？
現役エンジニアから話を聞いてみたいな～
こんなお悩みを現役インフラエンジニアが解決します。
☑本記事の内容
・ドキュメント作成で大事なこと
・僕が実際に書いているドキュメントとは？
・ドキュメントを書く苦労とは？
☑本記事の信頼性
・運用監視～設計構築・運用建付け等、インフラエンジニアとしての業務経験有り
・運用手順書等のドキュメントもいろいろ書いた経験有り
このように運用監視や設計構築等、様々なフェーズを経験してきました。
その中でもドキュメント作成は避けられない仕事の一つです。
ドキュメント作成をする主な理由は、こちらになります。
・お客様への納品が必要
・作業の属人化を防ぐ
・後から情報を探す際に必要(設定した内容等)
このように、エンジニアの業務をする上でドキュメントは非常に重要なものになります。
今回は、僕が業務でドキュメント作成をしていく中で大事だと思ったことについて、ご紹介していきたいと思います。
それでは、本題に入っていきたいと思います。
ドキュメント作成で大事なこと
僕がドキュメント作成をする上で大事だと思うことはこちらになります。
・フローを最初に決める
・ターゲットを絞る
・全体的に見やすくする
では、掘り下げていきたいと思います。
フローを最初に決める
フローを最初に決めるということがドキュメントを作成する上で大事です。
なぜなら、
- 後で修正がしやすいから
- 全体の手順を見通しやすいから
- 最初に決めておくとドキュメントを作成しやすいから
になります。
僕の体験談になりますが、作業手順書の作成の際にフローを冒頭に付けました。
業務で作業手順について説明する機会がありましたが、フローを記載したおかげで説明しやすかったです。
※実際に作業手順書を使用してもらいましたが、「見やすい」と評価してもらいました！
このように、フローを最初に決めておくと、ドキュメントが作成しやすくなります。
また、人にも説明しやすくなるので、良いことだらけです。
ドキュメントを作成する前にフローを決めておくと、いろいろメリットがあります。
ブログの見出しを決めておくような感覚です。
ターゲットを絞る
ドキュメントを確認する人間(ターゲット)の選定も大事です。
なぜなら、人によって技術レベルや理解する力が違うからです。
僕が気を付けているポイントは、こちらになります。
ポイント
・「誰がドキュメントを見るのか？」を意識する。
・経験が浅い人が見る場合は、用語の解説や説明を多く入れる。
このように、「誰が見るか？」ということを意識しています。
IT業界未経験者がチームに入ってきた場合は、主にその人のレベルに合わせた作業手順書を作成することを心掛けています。
例えば、Linuxコマンドの意味や作業影響等は詳しく記載するようにしています。
ドキュメントは、ブログと同じで見る人に合わせた内容で書くことが大事です。
チームの過半数の方が用語の意味が理解できるとしても、経験が浅い人が理解できていなかったら本末転倒です。。。
全体的に見やすくする
全体的に見やすいドキュメントにすることも大事です。
ドキュメントを見やすくすることによって、
- 誤解によるミスを防ぐことができる。
- 手順に対しての疑問点を減らすことができる。
- 作業効率が上がる。
というメリットがあります。
見やすいドキュメントにするために、僕がいつも心掛けていることはこちらになります。
ポイント
・フローや図を載せる。
・画像を多く使用する。
・作業影響を記載する。
・見出しや箇条書きを用いる。
実際にこちらを意識しながら業務で作業手順書を作成しました。
結果、見やすかったようでほぼ疑問点を聞かれませんでした。
このように、全体的に見やすいドキュメントにすることが大事です。
見やすいドキュメントの方がメリットが大きいです！
僕が実際に書いているドキュメントとは？
僕が実際に書いているドキュメントは、こちらになります。
・作業手順書
・仕様書
では、掘り下げていきたいと思います。
作業手順書
今まで書いてきたドキュメントの中で、作業手順書を作成する機会が一番多かったです。
例えば、このような作業手順書を作成してきました。
過去に作成した作業手順書(抜粋)
・ExcelVBAマクロの使用方法
・クラスター製品の構築手順書
・VDIの運用手順書
このように、運用手順書～構築手順書迄幅広く作成してきました。
作業手順書を作成する前に画面キャプチャを集めますが、ここで苦労することが多かったです。
画面キャプチャを集めるだけで1日の時間を使ったりします。
しかし、画像がないと見にくいので歯を食いしばってやっておりました！
他にも疑問点等を都度確認しながら進めていました。
インフラエンジニアをやっていると、作業手順書は一番書く機会の多いドキュメントだと思います。
作業手順書の作成は苦労の連続ですが、作成後に他の方も同じ作業ができるようになります。
そのため、属人化を防ぐことができます。
仕様書
「仕様書」についても作成する機会がありました。
仕様書とは？
・物事のやり方や順序を書き記した文書
・機械や建築などで、注文品の内容や図などを示した書類
※仕様書について詳しく知りたい方は、以下リンクを参照下さい。
作成した仕様書は、このようなものになります。
過去に作成した仕様書(抜粋)
・ExcelVBAマクロの仕様書
・クラスター製品に関する仕様書
・VDI運用についての仕様書
作業手順書と同様にいろいろ作成してきました。
現在は、僕が作成したPowerShellスクリプトについての仕様書を作成しています。
これも書くことが多く苦労することが多いです。
しかし、やっておくと後からメンテナンスしやすい等メリットがあるため、手を抜かずにやるつもりです。
仕様書についても、インフラエンジニアをやっていると書く機会が多いと思います。
後から情報を確認したい場合やメンテナンスをしたい場合に、仕様書があると非常に楽です。
ドキュメントを書く苦労とは？
ドキュメントを書く上で感じた苦労については、こちらになります。
・終わらない絶望感を感じる
・ドキュメントを書いている際中に眠くなる
では、掘り下げていきたいと思います。
終わらない絶望感を感じる
こちらは直近1年間で特に感じていることになります。
ドキュメントを書いていると「終わらない絶望感」のようなものを感じることが多いです。
なぜなら、
- 書くことが思い浮かばない
- 書いても書いても終わる気配がない
と思うことが多いからです。
例えば、作業手順書を作成する際にこのような絶望感を味わっています。
作業手順書を作成する際の絶望感
・構成が思い浮かばない
・書く内容が思い浮かばない
・1ページに書かなければならない内容が多い
特に構成が思い浮かばないときが一番辛いです。
前に進んでいる感覚がないですからね泣
このように、ドキュメントを書いていると終わらない絶望感を感じることが多いです。
ドキュメントを書いているときは絶望感を感じることが多いですが、
書き終わって見直しまで完了した場合、とてつもない達成感を感じます。
ドキュメントを書いている際中に眠くなる
ドキュメントを書いている際中に眠くなるときが多いです。
なぜなら、地道な作業が続くからです。
地道な作業の例はこちらになります。
地道な作業
・画面キャプチャ集め
・文字を書くこと
・作成したドキュメントの見直し
このように、地道な作業の連続です。
ここ1年は在宅勤務で紹介した地道な作業をやっているので、特に眠くなることが多いです。
そこで、このようなものを導入しました。
- スタンディングデスク
|
|
![[商品価格に関しましては、リンクが作成された時点と現時点で情報が変更されている場合がございます。]](https://hbb.afl.rakuten.co.jp/hgb/1e962299.d955fa31.1e96229a.2fbe8e11/?me_id=1260065&item_id=11223022&pc=https%3A%2F%2Fthumbnail.image.rakuten.co.jp%2F%400_mall%2Frcmdin%2Fcabinet%2F9t03%2F9t-l0-gsd120.jpg%3F_ex%3D240x240&s=240x240&t=picttext "[商品価格に関しましては、リンクが作成された時点と現時点で情報が変更されている場合がございます。]")
- 疲労軽減マット
サンワダイレクト 疲労軽減マット スタンディングデスク マット 腰痛対策 滑り止め加工 立ち仕事 耐水・耐油・耐菌 幅60cm ブラック 100-MAT009
Twitterでもご紹介しております。
https://twitter.com/satton6987/status/1349316985901916162
実際にこちらの環境に投資した結果、以前より集中力が増しました。
職場での勤務の場合は、たまに歩く等の息抜きが必要です。
このように、ドキュメント作成は地道な作業の連続なので、眠気対策は大事です。
まとめ : ドキュメントは「見やすさ」が大事！
今回は、エンジニアがドキュメントを作成する上で大事なことについてご紹介してきました。
一番大事なのは、「全体的に見やすいこと」になります。
他にも、
- フローを最初に決める
- ターゲットを絞ること
が大事だということもお伝えしました。
ドキュメント作成は地道な作業の連続なので、作成している時は大変です。
しかし、ドキュメント作成が完了すると達成感を味わうことができます。
そのため、諦めずに立ち向かって頂けたら幸いです！
現場からは以上です！
TwitterとYouTubeもやっています。
※インフラエンジニアの経験談や技術について発信しています。
