教えて!ドキュメント管理の改善ポイントとは?

◆ Live配信スケジュール ◆
サイオステクノロジーでは、Microsoft MVPの武井による「わかりみの深いシリーズ」など、定期的なLive配信を行っています。
⇒ 詳細スケジュールはこちらから
⇒ 見逃してしまった方はYoutubeチャンネルをご覧ください
◆ 次回のライブ配信について ◆
●マイクロソフトが提供するRAGアーキテクチャの詳解とデモを行うイベントを開催します。以下のリンクからご参加ください。

⇒ 2/27(火)19:00〜 RAG構築のためのAzure OpenAI Serviceリファレンスアーキテクチャ詳解 https://tech-lab.connpass.com/event/307678/

2016年9月号 「日経SYSTEMS」 の特集 「不要な文書はもう作らない!ドキュメントダイエット法」 に、
弊社技術部の武井(本ブログ投稿数No1) と水倉のインタビュー記事が掲載されました!

残念ながら記事で掲載しきれなかった 「ドキュメント管理の改善ポイント」 をおしみなくご紹介します!

point

1. 不要なドキュメントを作らない
実装に近いレベルの処理を記述した仕様書を作成せずに、内部仕様については外部仕様を元に実装したテストコードで実装するようにしています。合わせて、フレームワークを使ってどういったレイヤのクラス構造とするかといった設計方針を示す情報を必要なドキュメントとして作成するようにしています。

また、課題/障害管理表等の管理ドキュメントについては、RedmineやBacklogでチケットとして管理することで、「Excel+メール」の煩雑なやりとりを解消しています。

2. 実装と乖離しない「Deploy-readyなドキュメント」を作る
ドキュメントをメンテナンスしていく中で付き物の課題です。こちらについてはドキュメントから実装を生成するというアプローチを取っています。主に、テーブル項目や各種パラメータを定義した仕様書が該当します。テーブル項目であれば、ERDからテーブル項目定義書、DDLを生成し、さらにO/Rマッパー用SQL、ソースコード (Entity ModelやData Access Object) をプログラム的に生成します。
パラメータシートであれば、Cloudコマンドや構成テンプレートを生成しています。 (AWSであればCloud Formation、AzureであればResource Managerテンプレート)

このようにドキュメントが直接実装へ結び付く仕組みとすることで、ドキュメントと実装の乖離を防ぐ工夫をしています。ドキュメントをメンテナンスする目的がはっきりすることで、エンジニアのモチベーション維持に繋がる効果も期待されます。

以上、参考になりましたでしょうか?
ぜひ皆様のビジネスにお役立てください!

アバター画像
プロフェッショナルサービスチームの中の人。
ご覧いただきありがとうございます! この投稿はお役に立ちましたか?

役に立った 役に立たなかった

0人がこの投稿は役に立ったと言っています。


ご覧いただきありがとうございます。
ブログの最新情報はSNSでも発信しております。
ぜひTwitterのフォロー&Facebookページにいいねをお願い致します!



>> 雑誌等の執筆依頼を受付しております。
   ご希望の方はお気軽にお問い合わせください!

Be the first to comment

Leave a Reply

Your email address will not be published.


*


質問はこちら 閉じる