Q&A
こんばんは。
どんな相手に対する資料なのか記述した方が良いのではないですか？
利用者なのか技術者なのか経営者なのか、サービス自体の説明なのか、技術的な説明なのか、ソフトウェア的なものなのかハードウェア構成なのかとか、相手によって全然変わると思うのですが。そこから一般的に呼ばれている資料名が出てくれば回答につながりやすいと思います ^^
最近、運用しているサービスの
ソースコードに関する資料が欲しいという声をうけ
その資料を準備する必要があるのですが、
そもそもソースコードに関するの資料というものがどんなものなのか
全く想像がつかず、どんなものを用意すればよいのかも
わからず困っています。
よろしければ、その手の資料で参考になりそうなサイト、
書籍、アドバイスなどを是非ご教示いただきたく思います。
よろしくお願いします。
【追記】
資料は、エンジニア向けの資料と聞いております。
プロジェクトのフォルダ構造や各ファイルの役割などの説明、
サービスの運用の手順（サービスに何かの機能を追加する場合
どのファイルを編集すれば良いかなど）、基本的な処理の流れ
などが必要であるとのことです。
回答ありがとうございます。
質問内容に関して、不十分な点が多々ありましたので追記させていただきました。
今回はエンジニア向けの資料となりますので、エンジニア向けの資料とは
具体的にどんなものなのなのかを知りたく、質問させていただきました。
ハードウェア、ソフトウェア、その他の資料と色々必要なのですが、
私が担当するのはソフトウェア関連の資料の作成になります。
回答7件
0
書類を作るのはキリがないので、現実的に
重要なものを優先して作ることになります。
すると何が重要なのかという話になります。
その考え方は組織によって異なりますが個人的には、
資料を受け取る側の立場で作って欲しいと思います。
たとえばフレームワークなど他でも情報が入手できるものや、
ソースを読めば分かる部分は概要にとどめて、
なるべく属人性の高い部分、例外的な部分、
情報価値の高い部分を優先的に文書化してほしいです。
具体的にはたとえば障害発生時の復旧手順がそうです。
切り戻しの手順や復旧成功の確認法、復旧用の内製ツール、
バックアップや、もしそれも破損してたら
どうやったら障害前の地点まで戻せるのかとか。
まあ最低限、システム構成図と運用手順書と
シーケンス図などのUMLがあれば形になると思いますが、
自分が資料をもらう側に回ったときに、「この資料は良いな」とか
「こういう資料があれば良いのに」といったことを考えて頂けますと幸いです。
投稿2016/07/10 02:23
総合スコア5592
回答ありがとうございます。
現状すでに先方にはディレクトリ構成図と簡単な処理の流れについての
資料を送付しており、何かわからない点があればその都度質問してもらい、
それに対して返答するといった形で対応するというところに収まっております。
先方がどんな資料が欲しいのかというところが少々不明瞭ではあるため、
このような形になっておりますが、ひとまず何とかなってはいるので、
また必要に応じて色々考えていきたいと思っております。
0
運用しているサービスの資料が欲しい
というのは、
「どの様な立場の人」が、
「どんな目的」で
「どれくらいの粒度」の資料を欲しいと言っていますか？
資料というものはあくまで目的を達成するための道具でしかないので、
その部分が曖昧だとどんな素晴らしい資料があったとしても空振りになってしまいます。
*例えば、社長がサービス概要と利益率を知りたいのにデータベース設計資料を出しても意味が無いという感じです。
もし目的などが完全に明確になっていないのであれば、その辺りを明確にするのが一番最初で、
（明確にすればするほど少ない労力で目的にマッチした資料が作れます）
その後に適した手法や理論を探すという感じになるのかなと思います。
投稿2016/07/06 15:09
総合スコア18713
回答ありがとうございます。
質問内容に関して、不十分な点が多々ありましたので追記させていただきました。
また質問をする際には、なるべく具体的な形ですべきだと反省いたしました。
まず自分の目的を明確にし、伝える努力をしていこうかと思います。
主に設計資料が必要という事ですね。
これも多岐にわたるので、さらに詳細に必要な用途を明らかにする必要があるかと思います。
特に、
「その資料を必要とする人の技術レベルや知見」
については重要です。
新卒の開発者でも機能追加できるような資料なのか、要点だけ書けばわかるレベルの開発者を想定するか、などですね。
想定するロールと使用条件を想定して、必要なドキュメントを炙り出しましょう。
例えば、それなりに技術を持った技術者が新しい機能を追加する時にはどういった流れで順に作業をしていくのか？
と考えた場合、
・開発環境の構築
・フレームワーク等の学習
・新規機能の仕様確定に際する既存機能の確認
・外部設計
・内部設計
・機能の実装
・テスト(ローカル）
・テスト（ステージ環境）
・デプロイ
という感じの必要でしょうから、それぞれのフェーズで必要な資料を作る事になります。
*これが、採用しているフレームワークに精通している人を雇うという前提になるなら、フレームワークの学習や説明は必要なくなります。
個人的にどんなケースでも欲しい（無駄にならない）と考えるのは
・開発ポリシー及びコーディング規約
・ミドルウェアの構成、バージョンの情報
・プラットフォーム（データセンターやクラウド等の環境）
・HW情報
・フレームワークについての情報（学習方法や学習コストなどの知見も併せて）
*アプリケーション内のディレクトリ構成などはここに書く
・ユースケース図
・シーケンス図
・単位ごとの画面機能仕様所（システムの種類によって単位は変わると思います）
・DB設計に関する資料
・開発環境構築に関する手順書
・デプロイに関する手順書
・リポジトリに関する情報
・テスト方針及び手法のレギュレーション
あたりでしょうか。
0
サービスの資料と一言で書かれていますが、資料が欲しいという声をあげている方、つまり資料を読む方の立場や力量によって求められている資料は変わります。
- 社外的にサービスを売り込むための資料
- サービス利用者向けに細かなことやQ&A的なことを説明する資料
- 社内的にサービスの管理運用を説明するための資料
- 開発チーム用にサービスのプログラム的なことを説明する資料
- 問い合わせ対応用に受け答えの内容を決めておくための資料
などなど
まずは、どんな立場の人が資料を欲しているかを調査し、どんな情報を欲しているかを検証することが必要でしょうね。
そのあとは、一般的にその情報をどのように伝えているのかを調べて、同じような形の資料を用意すればゴールです。
投稿2016/07/06 15:14
総合スコア1895
回答ありがとうございます。
質問内容に関して、不十分な点が多々ありましたので追記させていただきました。
今回はエンジニア向けの資料となりますので、エンジニア向けの資料とは
具体的にどんなものなのなのかを知りたく、質問させていただきました。
１．プロジェクトのフォルダ構造
２．各ファイルの役割などの説明
３．サービスの運用の手順
４．基本的な処理の流れ
質問文にあったこの４つを説明する資料を作ればいいですね。
１と２はフォルダ構造をツリー状の図で書いて、「これはなになにを担っている」という感じで軽く説明すればいいです。詳しく書こうとすると時間がいくら合っても足りないため、要点だけ取り出して書くのがコツです。
３．先ほどの図を参考資料として提示して、確率的に高そうな事例を幾つか書いていけばいいです。また、コンフィグファイルみたいなものに関しては、できるだけ詳細に書くことをおすすめします。将来いじる可能性が高いところですので。
４．処理の流れを図で描きます。アクティビティ図とシーケンス図があればいいのかなと
ここは気合を入れて詳細に書くより、概要がわかればいいと考えていいと思います。
これらのマニュアル製作のコツは……
・時代は変わるのでサービスも永遠には続かないこと（資料は数年後まで想定すれば十分）
・システムの改変や周りの環境の変化で情報は古くなる性質をもつということ（細かな内容は変化する）
・マニュアル製作もコストが掛かるということ
・大量の情報は大切な情報を覆い隠してしまうということ
ということを考えて、あまり変化することのない全体的な視点を伝えることです。
0
先に投稿された方と、重複している内容がいくつか入ってしまいますが、その辺りはご勘弁を。
で、まず辛口で、質問と離れてしまいますが、、、
さて早速ですが、
今回の質問の件、頼んだ方も、頼まれた方も（あなた）、スキル的にミスマッチなのかと思います。
・頼まれた方が何をすればわからず、このようなサイトに質問をしなければならないという事、
・その事を頼んだ方も理解していない（おそらく意地悪で無い限りは何か成果を出すと期待している）、
これは非常に不幸な状態であります。
今後、いろいろなお願いをされるけど、わからない事ばかりで・・・仕事が増えて、嫌になって、ブラック化してく臭いがします。
一度、頼んだ方に、なぜ自分に頼んだのか、正直現在の自分の知識では、頼まれた事に、現状ではどうかいとうすればいいか分からない、と正直に言った方が、よいような気がします。
スキル向上の為に、難しい経験のない仕事をだしているのかもしれませんし、頼んだ側が依頼する相手の選択ミスをしているのかもしれません。最悪単なる意地悪なのかもしれませんし。
まあ、会社の雰囲気など一切わかりませんので、単なる理想論ですが。
あと、ドキュメントですが、いろいろ作る前に、すでに存在するドキュメントをまずは探してみてはいかがでしょうか？
ある程度の、規模の開発であれば、全社的にとか、開発部門でとか、
・開発標準（あるかないかは５０％かな？！）とか、それっぽい資料（は以外とあるかも）
要するに、開発するには、こんなルールで、こんなドキュメントは残しておこうね、品質はどうゆう定義にして、などなど、開発に関する関連の、根っこのルールが定義してある物です。
・上記の開発標準で定義されたドキュメント類
要件定義書
外部設計
システム設計
概要設計仕様
詳細設計仕様
コーディング規約
命名規則（モジュール、ファイル、変数・・・）
単体・結合・運用・システム・・・テスト仕様
テスト結果
品質関連の資料
リリース判定関連の資料
運用関連の資料
などなど、いろいろでてくるかと思います。
もし、存在しないのであれば・・・作るしかありませんが、相当システム全体やプログラムの内容について熟知している必要がありますので、
もしあなたがソースコードを読めないとか、もし読めたとしても、上記のようなドキュメントの内容の想像がつかないとかの場合には、正直なところ、資料として起こすことは難しいかと思います。
やはり、依頼人と一度相談をされたほうがよいような気がしますが・・・。
投稿2016/07/10 08:29
総合スコア1283
回答ありがとうございます。
ItoTomonori様のご意見ごもっともでございます。
私が現在つとめているところでは、その手の資料制作のノウハウがまったく
存在せず、また私も資料制作の経験があまりないため
かなり手探りの状態になってしまっているのが現状です。
すでに先方にはディレクトリ構成図と簡単な処理の流れについての
資料をテキスト形式で作成したものを送付しており、
何かわからない点があればその都度質問してもらい、
それに対して返答するといった形で対応するというところに収まっております。
スキル的なミスマッチは確実に起きているとは思いますが、
少なくとも何かしらの形では対応できてはいるので
現状これで様子をみてみるしかないかなという感じです。
0
ソフトウェアのドキュメントの例として UML というものがあります。
...
オブジェクト指向をベースとするソフトウェアの構造をソースコードよりも抽象化した形で構造的かつ形式的に表記する言語である．
...
ソースコードについて、単にファイル一覧 (フォルダ構成とファイル名...) は納品資料の一部にはなりえますが、
チームへの新規メンバーへの説明、保守エンジニアへの説明
などには、ほとんど役に立ちません。
設計思想と、それをどのようにシステムとして実装したか の理解が、開発・保守には重要だからです。
そういったことを伝えるに
クラス図
配置図
ユースケース図
シーケンス図
ER図
などが必要になります。
さらに 場合によっては API ドキュメント、単体テストコードも必要になるでしょう。
(テストコードは、動作チェックだけでなく、コードの実際の振る舞いが記述してある動作可能なドキュメントの役目もあります)
投稿2016/07/07 14:45
総合スコア22324
回答ありがとうございます。
ソフトウェアのドキュメントをまとめるにあたり、
UMLは有用な手段のひとつではあると思います。
UMLに関しては、クラス図の作成経験が数度ある程度ではありますが
必要に応じてクラス図やその他UMLの図を作成も検討していこうと思います。
0
hmaeyama さんの立場がどのようなものなのか不明ですが、どのような依頼を受けたのか、正確に質問して下さい。
運用しているサービスの資料が欲しいという声をうけ
その資料を準備する必要があるのですが、
そもそもプロジェクトの資料というものがどんなものなのか
全く想像がつかず、どんなものを用意すればよいのかも
わからず困っています。
なぜサービスの資料がほしいと言われているのに、プロジェクトの資料を用意するのか、意味が分かりません。
依頼された内容は以下ではないですか？
運用しているサービスの資料の○○プロジェクト時の資料とがほしい。
サービスの構築プロジェクトの完成図書（運用フェーズにあるサービスで、プロジェクトの資料といえば、一般的にこれを指すのではないかと思います。）であれば、新たに作る必要すらありません。
投稿2016/07/06 16:35
退会済みユーザー
総合スコア0
回答ありがとうございます。
ご指摘ごもっともでございます。使用している表現が良くないなと反省しております。
必要なのは、現在運用しているサービスのソースコードに関する資料になります。
そのあたりをどういった形で資料にまとめていけばよいかで現状悩んでいる状態です。
理解しました。ソースコードを束ねる単位として「プロジェクト」という呼び方を使用していたんですね。
運用中のサービスであれば、運用ドキュメントとしてまとまっていて良さそうな資料ばかりなので、以下のいずれなのか、指示内容を確認したほうが良いです。
1,既存資料を、特定目的に対して、粒度を揃え報告する資料の作成
2,運用ドキュメントが整理されていないので、運用ドキュメントの作成、再整理
エンジニア向けの資料ということは2のような気もしますが、運用ドキュメントがまるまる整理されていないとは考えにくいので、確認したほうがよいかと。
0
追記を見る限りほとんどそのまま、「システム構成図」と「運用手順書」かなと思いますが、
それぞれ検索してみてください。
機能を追加する場合どのファイルを編集すれば良いか
これは詳細設計書があれば間違いないんでしょうが、流石に今からは作れないでしょうから・・・うーん
短時間で仕上げるなら「ファイル構成図」辺りですかねぇ・・・
新規参入の開発者向けなのか引き継ぎなのかとかによっても変わるでしょうね。
別の方の回答も待ちましょう。
投稿2016/07/06 16:10
総合スコア2208
あなたの回答
tips
プレビュー
