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

2016-09-23 Azure, クラウド 0

◆ Live配信スケジュール ◆
サイオステクノロジーでは、Microsoft MVPの武井による「わかりみの深いシリーズ」など、定期的なLive配信を行っています。
⇒ 詳細スケジュールはこちらから
⇒ 見逃してしまった方はYoutubeチャンネルをご覧ください

【5/21開催】Azure OpenAI ServiceによるRAG実装ガイドを公開しました
生成AIを活用したユースケースで最も一番熱いと言われているRAGの実装ガイドを公開しました。そのガイドの紹介をおこなうイベントです!!
https://tech-lab.connpass.com/event/315703/

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

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

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

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

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

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

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