Kompira

Menu Menu

Column

2020/09/30

技術ドキュメントの課題

こんにちは。フィックスポイントの冨です。

最近、普段あまり触らないようなシステムを、ドキュメント記載の手順にしたがって 操作する機会が何回かあったのですが、想定通りに完了しない。
おかしいなあとスクリプトや設定ファイルの中身を読み始めるのですが、 明らかにドキュメントに記載されていない設定項目があったり、 スクリプトを動かす前に必須の設定事項があったりと、いろいろと驚かされたわけです。

直近の担当者に問い合わせてみると「それは記載漏れでしたね。」という場合ともかく、 「ああ、そこ、みんなハマるんですよね。」となると、おいおい!となります。
分かっているなら更新しておいてくれよと。

ドキュメントの重要性はみんな理解されているのですが、 どのように書くか、どのようにメンテナンスしていくかについては、 意外と二の次にされている事も多いなあと感じます。
特に開発に忙しい時はどうしてもドキュメント執筆の時間の優先度は下げられてしまいますよね。

運用設計の段階で、用意すべき文書の標準の整備が行われているところも多いかと思いますが、 実際の文章を読むと、MECE=抜けもれなくダブりもなく網羅するとか、用語定義の明確化、 暗黙の了解事項が多くてハイ・コンテキストな文章になっていないかなど、 いろいろと気になる所が出てきます。

技術ドキュメント執筆については、あまり参考書は多くないのですが、 どのような文章を用意して、具体的に何を書くべきかについては、 近藤誠司さんの「運用設計の教科書」という本は参考になると思います。

文章も書き慣れていないとハードルは上がる一方ですが、 Sphinxなどの作成支援ツールなどもあるので、 ご興味ある方は研究してみると良いでしょう。

文書管理も、以前は「Excelファイルに、”案件名-YYMMDD.xlsx”って日付をつけているんだよ」と 自嘲気味に話される事も多かったですが、 最近は差分・履歴管理もできるドキュメント管理サービスやネットワークドライブも増え、 ずいぶんと楽になりました。

時間や予算の制約のある中、きちんと分かりやすく書き切るのは難しいですが、 リモートワークの拡大、メンバーの流動性向上、ライフサイクルの短期化が進む昨今では、 ドキュメントの品質は、致命的な知識のロストを生む可能性を秘めています。
将来的な業務品質を担保するためにも、ブラッシュアップを心がけていきたいものです。

コラム一覧
2024年
2024.03.27
自動化する側になれますか?
2024.03.21
システム障害の教訓
2024.03.13
NIST CSF2.0のリリース
2024.02.28
AI企業がけん引する株式市場
2024.02.21
プロアクティブな「予防保守」に向けて
2024.02.14
CentOS 7のEOLに向けて
2024.01.31
情報セキュリティ10大脅威 2024が発表
2024.01.24
ネット出願のメールのトラブル
2024.01.17
Gmailの迷惑メール対策が間近
2023年
2023.12.27
2023年は生成AIの一年でした
2023.12.20
「プラットフォーム・エンジニアリング」は流行るか?!
2023.12.13
今年も年末でアドベントカレンダーの季節
2023.11.29
今日はOpsSummit 2023の日
2023.11.22
AI技術利用のモラル
2023.11.15
IT業界での燃え尽き症候群
2023.11.14
セキュリティガイドラインのプラクティス集が公開
2023.10.30
相次ぐ大量情報漏洩事件
2023.10.27
50年間トラブル無しのシステム
2023.10.25
ケイパビリティの強化
2023.10.24
「豆腐」という構成管理ツール
2023.10.23
キャリアパスへの不安感
2023.10.20
業務属人化の是々非々
2023.10.18
「運用設計の教科書」の改訂版が出ます
2023.10.17
ガートナーが発表した2つのハイプサイクル
2023.10.16
「デジタルスキル標準」の改定
2023.10.13
お盆休みといえばセキュリティー
2023.10.12
「形式主義」と「実質主義」
2023.10.11
増えるシステム、増えない人
2023.10.05
ニトリに見るITリテラシーの底上げ
2023.10.03
「自由なソフトウェア」の理念
2023.10.02
Interop2023に出展しました
2023.09.29
経産省 ASM導入ガイダンスを公開
2023.09.28
業務効率化に際して大事なこと
2023.09.27
「監視」に疲れ切っていませんか?
2023.09.26
リモート勤務の是々非々、再び
2023.09.25
大型連休の準備は出来ましたか?
2023.09.22
新しくリーダーになった人へ
2023.09.21
運用にChatGPTにどう使う?!
2023.09.20
「閉域網神話」の崩壊
2023.09.19
LLM戦国時代の到来
2023.09.14
作業自動化のボトルネック
2023.09.13
作業自動化の6ステップ
2023.09.12
IPAよりDX白書2023
2023.09.11
チャットボットAIが大流行
2023.09.07
リスキリングと35歳定年説
2023.09.06
USビッグテックでリストラ始まる
2023.09.05
デジタルスキル標準の発表
2023.09.04
SBOMとサイバー防衛の取り組み
2023.09.01
ITインフラを何で勉強してますか?
2023.08.31
業務自動化で避けるべき落とし穴
2022年
2022.11.30
AIは運用業務を変えるか?
2022.11.23
テックジャイアントのリストラとDX
2022.11.16
ヒヤリ・ハット対応から始めるトラブル対応
2022.11.09
ソフトウェアエンジニア受難の時代
2022.10.26
DXレポート2.2が訴える戦略の重要さ
2022.10.19
「効率化」の目線をあわせる
2022.10.12
デジタル化に向けた「大胆な一手」
2022.09.28
自動化の前に手順書の見直し
2022.09.14
セキュリティー投資はトップダウンで
2022.08.31
DXの落とし穴
2022.08.24
業務自動化への展望
2022.08.17
ガートナー社の2022年の新興技術ハイプ・サイクル
2022.08.10
医療逼迫と業務改善
2022.07.27
”Web3”入門書の炎上
2022.07.20
ゼロトラストの設計と実装
2022.07.13
障害対応は事前の準備から
2022.06.29
尼崎市の個人情報インシデントの件
2022.06.22
リソース不足が招いた半田病院の悲劇
2022.06.15
MSPのセキュリティーアドバイザリー
2022.06.08
シリコンバレーは黄色信号?
2022.05.25
今年もやります。OpsSummit 2022
2022.05.18
「現場猫」案件にみる甘い危機管理
2022.04.27
運用管理に向いているDMAICフレームワーク
2022.04.20
お勧め本「システム運用アンチパターン」
2022.04.13
IPA 「DX実践手引書」の改訂版を発表
2022.03.31
春は引継ぎのシーズン
2022.03.24
「なぜなぜ分析」の使い方
2022.03.16
マルウェアEmotet再流行
2022.03.09
省エネモードのエンジニア
2022.02.24
ヒューマンエラーを防ぐには
2022.02.16
インフラ維持と式年遷宮
2022.02.09
Web3.0とP2Pの復権
2022.01.24
JIS規格に学ぶリスクマネジメン
2022.01.19
多すぎる通知の副作用
2022.01.12
2022年のインフラ技術
2021年
2021.12.29
今年もお世話になりました
2021.12.22
品質レベルはステージごとに変わる
2021.12.15
ログ出力ライブラリLog4j脆弱性の影響
2021.12.09
リモート作業の問題点
2021.11.24
メタバースに未来はあるか
2021.11.17
インシデントとの向き合い方
2021.11.10
DXは差別化要素を作るための投資という視点
2021.10.27
監視の拡張としてのオブザーバビリティ
2021.10.20
良い自動化、イマイチな自動化
2021.10.13
みずほ銀のトラブルから学ぶ
2021.09.29
クラウドDBで時短
2021.09.22
そろそろWindows 11が到来します
2021.09.15
トラブル対応の心がけ
2021.09.08
10/10は「デジタルの日」
2021.08.25
運用なき開発を避ける
2021.08.18
日本のDXの最前線
2021.08.12
DXとアジリティ
2021.07.14
ポストコロナで会議室が足りなくなる?
2021.06.30
自動化の技術選択
2021.06.23
業務の自動化は入り口にすぎない
2021.06.16
データ入力のお作法
2021.05.26
「苦労に価値がある」という価値感
2021.05.19
「運用でカバー」する公共システム
2021.05.12
VUCAの時代を生き抜くスキル
2021.04.28
デジタル敗戦からの復興はなるか
2021.04.21
PCの「基本的人権スペック」
2021.04.14
お勧め書籍「運用改善の教科書」
2021.03.31
運用スタッフの大部分はリモートワークへ
2021.03.24
定型業務をプログラマブルに
2021.03.17
監視疲れを起こさない工夫
2021.03.08
MSの無料RPAは自動化の起爆剤となるか
2021.02.22
終わりなき開発とインフラ運用
2021.02.17
作業を自動化しても業務が効率化しない場合
2021.02.10
Cocoaのバグが4か月も発覚しなかった話
2021.01.27
「クソどうでもいい仕事」を考える
2021.01.26
「クソどうでもいい仕事」を考える
2021.01.20
自動化の次の課題としてのAIOps
2021.01.13
DXレポート2が公開されました
2020年
2020.12.21
今年もお世話になりました。
2020.12.16
どうなる? 2021年のITインフラ
2020.12.09
アドベント・カレンダーの季節です
2020.11.11
AI・業務自動展で見聞きしたツライお話
2020.11.04
「7番セカンド」な仕事
2020.10.21
システム監視とアラート地獄
2020.10.19
機械学習とシステム運用
2020.10.14
形あるものは壊れる。システムも。
2020.09.30
技術ドキュメントの課題
2020.09.23
デジタル庁に寄せる期待感
2020.09.16
ローコード開発とエンジニア不要論
2020.09.09
技術の近未来予測とニューノーマル対応
2020.08.26
“アンチフラジャイル”な考え方
2020.08.19
カオスエンジニアリングという考え方
2020.08.12
運用が稼ぐ時代
2020.07.29
AIシステムの運用
2020.07.22
新宿に宿泊でTDLにGoToは対象外?
2020.07.08
チェック回数を増やしても意味がない
2020.06.24
「時代はクラウド」発言と政府インフラ
2020.06.17
システムの標準化とスキルセット
2020.06.10
「2025年の崖」からの転落事故
2020.05.20
先端IT“非”従事者は勉強不足 from IP
2020.05.12
スペイン風邪にみるコロナ第二波へ備
2020.04.30
「運用でカバー」という魔法の言葉
2020.04.26
未然に防いだトラブルは評価されにくい
2020.04.22
リモート勤務で重要性を増す「ゼロ・トラスト」セキュリティ
2020.04.15
オンラインイベント「Ops Summit2020」開催!
2020.04.15
コンサルは「標準化しろ」とは言うけれど
2020.04.08
オンライン”Zoom”会議のセキュリティー問題
2020.03.23
ドキュメントで見かける”Day 2オペレーション”
2020.03.18
今、売れまくっているITサービス
2020.03.11
出社している場合じゃないご時世
2020.02.26
新型コロナウィルス対策に学ぶトラブル対応
2020.02.19
バレンタインデーにシステム統合の本がバカ売れ
2020.02.12
ハイパーオートメーションの時代
2020.01.29
インフラ運用リーダーが備えるべき10の能力
2020.01.22
障害発生時の夜中に叩き起こす技術
2019年
2019.12.11
RPAとRBAと運用自動化
2019.12.11
年末年始に読む運用関連本
2019.11.27
業務フローの「こんまり」のお勧め
2019.11.20
「システム運用自動化」はスモールスタートで
2019.11.13
運用事故では人を責めない
2019.01.15
話題の「クラウドネイティブ」とは何か?