IT知識ゼロ広報の業界勉強奮闘メモ⑥：エンジニアのドキュメント作成について

皆さんこんにちは！Mavel広報の渡邊です🌸

まだまだエンジニアさんのお仕事は未知の領域ですが、
引き続きコツコツ勉強を重ねて、より密度の高い記事をお届けできるように頑張ります🔥🔥

さて今回は、開発や運用においてエンジニアさんが作成、または関わるドキュメントについて調べました！

システム開発に用いるドキュメント

RFP（提案依頼書）

クライアントが開発を請け負うシステム会社に対し、開発を依頼するシステムの要件について明文化したもの。5W1H(目的、予算、納期、運用等)で明記するのが基本。

（引用：https://kaizen-penguin.com/about-rfp-sample-9037/）

要件定義書

要件定義とは、開発者視点からシステム構築における要求をまとめ、あらかじめ具体的な進め方や全体設計を決めること

システム開発を進める上で実施すべき業務内容を事前に想定し、誰が見ても理解できるように文書化、要件定義で定められたシステムの全体像や細かい機能までをまとめてあるドキュメントのこと。

～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～
（引用：https://notepm.jp/sharing/190de8bd-5e83-40f6-ab5e-1bc2f231beb8）

基本設計書

要件定義の内容をもとに、要件を満たすために必要機能を洗い出して設計し、どのような画面になるか実装する機能などを定めるものを「基本設計書」という。具体的な画面のレイアウトや入出力する帳票フォーマット、管理項目や実装したい機能などを使用するシーンと運用するシーンを想定しつつ設計していく。

●青森県観光情報サイトの基本設計書が公開されていました👀
⇒ https://www.pref.aomori.lg.jp/soshiki/kkokusai/shinkanko/files/10.kihonsekkeisyo.pdf

思っていた以上にかなり詳細に記載するんですね。。。🫢
この段階でしっかりと具体的に形にすることにより、クライアントとのすり合わせにおいて相違なく、より円滑に開発を進めることができるんですね👀

詳細設計書

システムの大枠を作った基本設計の内容を細分化し、その処理内容をプログラム化しやすい方法でまとめたもの。

こちらのQiitaの記事が非常に勉強になりました！
⇒ https://qiita.com/minimumskills/items/556e963c54e95c0a540a

記事の中から例として一つ共有いたします👀

場合に応じてユースケース図やシーケンス図、クラス図など、図を使い分けたりもするんですね🫢

テスト仕様書（単体テスト仕様書 / 結合テスト仕様書 / システムテスト仕様書）

動作確認をするためにテスト項目を記載した仕様書のこと。

単体テスト仕様書：1つ1つのプログラムを単体で動かし、その共働を検証するためにテスト項目を記載した仕様書

結合テスト仕様書：各プログラムを繋ぎ合わせて一つの機能として正しく動くかどうかを検証するための、テスト項目を記載した仕様書

システムテスト仕様書：システムを総合的に操作して正しく動くかどうかを検証するための、テスト項目を記載した仕様書

各テストを実行後、その都度結果を記入する成績書もある。

運用マニュアル

納品後に、クライアン独自に一連の運用業務が行えるように手順を記載したもの。
システム会社とクライアントの双方で協力しながら作成するのが一般的。

まとめ

いかがでしたか？👀

今回私が調べて共有させていただいたもの以外にも、エンジニアさんが開発運用の過程で関わるドキュメントはあります。
共有させていただいたものだけでも、エンジニアさんに求められているドキュメント作成力の高さを実感いたしました。

ドキュメントはチーム内での正確な共通認識の手段となるため、全ての人にわかりやすく言語化するだけでなく、場合によっては図なども用いて作成が必要なんですね🤔

先月Mavel株式会社ではnoteにて「アドベントカレンダー」という、12/1~12/25の期間25名のエンジニアさんに1記事ずつ執筆していただき、1日1記事ずつ公開していく・・・といったイベントを行ったのですが、その時に、エンジニアさんが作成した記事のレイアウトや、表現の上手さなど、記事全体の読みやすさに驚きました🫢🫢