質問をすることでしか得られない、回答やアドバイスがある。

15分調べてもわからないことは、質問しよう!

ただいまの
回答率

90.61%

  • PHP

    19882questions

    PHPは、Webサイト構築に特化して開発されたプログラミング言語です。大きな特徴のひとつは、HTMLに直接プログラムを埋め込むことができるという点です。PHPを用いることで、HTMLを動的コンテンツとして出力できます。HTMLがそのままブラウザに表示されるのに対し、PHPプログラムはサーバ側で実行された結果がブラウザに表示されるため、PHPスクリプトは「サーバサイドスクリプト」と呼ばれています。

ドキュメントの作り方が分かりません。

解決済

回答 4

投稿

  • 評価
  • クリップ 2
  • VIEW 1,739

YukiSiina

score 7

今会社の研修でPHPを使った自作のシステムを開発しているのですが、トレーナーの方にドキュメントを作るようにと指示を受け、自分で調べてみたのですがどのように作ればいいのかさっぱり分かりません。
自分で作成した物には、変数の使い道、どのページに移動するのか、メソッドの役割を箇条書きにしたのですが、こんな物で良いのでしょうか?何か付けくわえた方がいい内容があれば教えてください。
よろしくお願いします。

  • 気になる質問をクリップする

    クリップした質問は、後からいつでもマイページで確認できます。

    またクリップした質問に回答があった際、通知やメールを受け取ることができます。

    クリップを取り消します

  • 良い質問の評価を上げる

    以下のような質問は評価を上げましょう

    • 質問内容が明確
    • 自分も答えを知りたい
    • 質問者以外のユーザにも役立つ

    評価が高い質問は、TOPページの「注目」タブのフィードに表示されやすくなります。

    質問の評価を上げたことを取り消します

  • 評価を下げられる数の上限に達しました

    評価を下げることができません

    • 1日5回まで評価を下げられます
    • 1日に1ユーザに対して2回まで評価を下げられます

    質問の評価を下げる

    teratailでは下記のような質問を「具体的に困っていることがない質問」、「サイトポリシーに違反する質問」と定義し、推奨していません。

    • プログラミングに関係のない質問
    • やってほしいことだけを記載した丸投げの質問
    • 問題・課題が含まれていない質問
    • 意図的に内容が抹消された質問
    • 広告と受け取られるような投稿

    評価が下がると、TOPページの「アクティブ」「注目」タブのフィードに表示されにくくなります。

    質問の評価を下げたことを取り消します

    この機能は開放されていません

    評価を下げる条件を満たしてません

    評価を下げる理由を選択してください

    詳細な説明はこちら

    上記に当てはまらず、質問内容が明確になっていない質問には「情報の追加・修正依頼」機能からコメントをしてください。

    質問の評価を下げる機能の利用条件

    この機能を利用するためには、以下の事項を行う必要があります。

回答 4

checkベストアンサー

+3

これは永遠のテーマですね。
ドキュメントの作成・メンテナンスについては、100人いれば100通りの持論があり、また皆が皆、常に試行錯誤(=改善?)しているというのが正直なところではないでしょうか?

しかし、それでは仕事にならないので、どんなプロジェクトであれ、多かれ少なかれ「プロジェクト標準」というものがありますし、プロジェクトの最初の工程として、どんなドキュメントを成果物として作成するかをお客様と認識合わせするプロセスがあります。

それで、外部の人の意見、工夫している点は非常に参考になるのですが、まずは YukiSiinaさん ご自身の会社ではどんな「標準」が定められているのか、諸先輩はどのようなドキュメントを書いていらっしゃるのかを「良く見て学ぶ」のが先決です。

内容を眺めてみても、最初は全く分からないかもしれませんが、初めは
  • ドキュメント体系(どんな種類が作成されているか)
  • 各ドキュメントの章立て(書かれている項目)
  • どんなフォーマットや文体で書かれているか
のような「見た目」だけでも良いので、良く見て学んでください。

研修ではどの程度のプログラム(システム)を作成されるのか、またどの程度のドキュメントが求められているのかが全く分からないので、具体的なコメントができませんけれども、是非とも
  • 実装(プログラムのソースコード)の説明を書くのではない
  • プログラム(システム)の仕様を書く
という点を意識して書かれると良いと思います。

簡単なコメントは必要だとしても、細かな実装はソースコードを読めば分かるようになっているべきです。
一方、どのような入力に対してどんな結果を返すか(どんな動作をするか)は、実装を進める際の道標になると同時に、出来上がったものが「仕様通り」かどうかを判定する物差しでもあるので、必須です。

それと、研修中はカリキュラムの関係で時間が無いかもしれませんが…
最初は誰でも初心者なので、たとえうるさがられても、一気に完成させようとせず、要所要所で小まめに見てもらう(=レビューしてもらう)ようにしてください。
どんなベテランでも品質担保のためにピアレビューが欠かせないのですが、慣れないうちは尚のこと頻繁にレビューしてもらうことで、早く「標準」を身につけられるようになります。

以上が初心者向けの提言でした。
---------------------------------------------------------------------------------------------------------------------------------------
これから先は、少し長くなりますが、ドキュメンテーションに関する持論です。
言うは易く行なうは固しですが…

ちょっと逆説的ですが、良いドキュメンテーションの最大の秘訣は、「極力書かない」ことです。
つまり、本当に「必要不可欠な情報を厳選」し、できるだけコンパクトに書くべきであり、しかも、後で読むために書くのではなく、「必要な時」に「必要な分」ずつ書くのが鉄則です。

というのは、ドキュメンテーションにおいて最も問題となるのは、必要なドキュメントが不足している事ではなく、存在しているドキュメントが「実情と乖離」してしまう事だからです。嘘を書いてあるドキュメントほど厄介なものはありません!
実際に動いているシステムとの整合性を維持するコストは、ドキュメントの量に比例して爆発的に増大します。

しかも、多くの場合、次にドキュメントを詳しく読むのは、システム/ドキュメントに変更を加える必要が生じた時ではないでしょうか?

ですから、大量のドキュメントを「後追い」で作成する事は、生産性を著しく阻害する一方で、品質の向上にはそれ程役立たないのです。

ドキュメントと言ってもいろんな種類がありますし、分類の仕方にも色々な流儀がありますが、設計書を「外部設計書/内部設計書/詳細設計書」と分類する流儀について少しコメントします。
これはウォーターフォール型開発プロセスの場合の一般的な分類です。

#そもそもドキュメントとして、いつ何をどこまで書くかは、開発プロセスと密接に関わっているので、ドキュメントの事だけを切り離して議論しても意味がないのですが。。

「要件」通りのシステムを作成するために、外部設計→内部設計→詳細設計と段階的に「仕様」を詳細化し、具体的な「実装」(=コーディング)へとブレークダウンして行くので、「外部設計書/内部設計書/詳細設計書」と形式的に分けて作成すると、類似の情報がいろんな場所に分散されてしまい、整合性の維持が困難になります。

それで、工程別ではなく「内容」によって分類し、外部設計の時点ではその時点で必要な情報だけを記載します。次いで、内部設計工程では、その時点で詳細化された情報を、同じドキュメントに「追記」します。
このように関連する情報を一箇所に集約させる書き方をする、しかも体裁を整えるために後追いで書くのではなく、設計上「必要なタイミング」で「必要な情報だけ」を記載して行くことで、品質を作り込むための道具とすることができます。

システム設計において、モジュール分割はとても重要な作業なので、モジュール間の依存関係を視覚的に確認できるダイアグラムを書くのは非常に有用です。
一口にモジュール間の依存関係といっても、目的に応じて様々な表現法がありますので、「プロジェクト標準」に沿った書き方に早く慣れてください。

一方、詳細設計書はソースコードと密接に関連しているので、別ドキュメントにするのではなくソースコードと一体で管理できるようにすることが望ましいです。

とはいえ、ソースコードはリファクタリング等で大きく変更される可能性があるので、必要以上に詳細にコメントを記載する事は得策ではありません。
変数の説明をコメントに記載する位なら、意味の分かる変数名にリファクタリングする方がずっと意味があります。
むしろ、各部分の処理の意味、処理の前後でデータフォーマットがどのように変化するか、その実装方法が採用された経緯など、システムの仕様を後から思い起こすのに役立つ情報を簡潔に記載します。

もしPHPUnitのようなテストツールを使用可能なら、テストケースの詳細な説明をコメントに記載することで「動く詳細設計書」とすることができます。(ソースコードの場合とは逆に、テストクラスのコメントは仕様を詳細に説明するべきです。)

一般に誤解されている点ですが…、XXUnitのような単体テストツールは、文字通り単体テストのためのツールでテストクラスは必要に迫られて泥縄式に作成されるケースが多いですが、元々はテスト駆動開発プロセスにおける詳細設計のためのツールとして開発されたものです。
詳細設計時には、テストクラスの「判定条件」(=仕様)と、モジュールの骨組みだけを記載します。
実装工程では、実際に仕様通りに動くことを確かめつつモジュール内部を作り込んで行きます。

こうして実際に必要なタイミング(詳細設計&実装の工程)で作成したテストクラスは、仕様確認やリファクタリングなど必要な時にはいつでも実際に動かして「使う」ことができます。
このような詳細設計書であれば、品質の作り込みに直接役立つと同時に、ソースコードと整合性の取れていることが常に保証されています。

以上は「理想」であり、現実はなかなか理想通りに行かないものではありますが、しっかりとしたポリシーを持った上で、個々のドキュメントの具体的な書き方を学んで行くと良いです。

この部分については、まずは社内のお手本に目を向けることが重要ですけれども、ネット上にも有用な情報が多数見つけられると思います。

手始めに、下記の「まとめ」を足掛かりとして、色々な解説やサンプルに目を通してみてください。

(参考)仕様書を書くための技術

以上、いくらかでもご参考になれば幸いです。

投稿

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

  • 2015/08/17 09:56

    詳しい説明をありがとうございます。
    自分なりに分かりやすくシンプルに作る事が大切なのですね。
    社内にはお手本のような物がほとんどないので、リンク先を参考にさせて頂きます。
    ありがとうございました。

    キャンセル

+2

ドキュメントにも用途があります。例えば一緒に開発する人と、そのシステムを利用する人で内容が異なります。YukiSiinaさんが上げられた

  • 変数の使い道
  • どのようにページが遷移するか(画面遷移)
  • メソッドの役割

は開発者向けのドキュメントと言えるでしょう。なので、利用者向けのドキュメントがあると良さそうだな、と感じたのが1点。

その他にも下記の内容があると喜ばれるのではないでしょうか?

  • そのシステムがどういう目的で作ったものなのか?なんのためのものなのか?
  • システムを構築する時にやる手順(インストール作業支援)

ドキュメントは、今いる人々のために書くのではなく、そのシステムにたずさわる未来の人々のために書くものです。今回は研修で作成されているようですので、「未来の人々」はあまり意識しなくても良いかもしれませんが、実際のお仕事ではそのあたり意識されるとよいです。

投稿

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

+1

システム設計~構築~テスト辺りのドキュメントの資料としては、
以下の資料が良くまとまっていて参考になります。

http://www.slideshare.net/TAM_slideshare/5-13678562?qid=e21e5ee6-1da8-4d61-aecc-e6a80ff001cf&v=qf1&b=&from_search=11

前の方のおっしゃる通り、どの視点のドキュメントかで、回答も
変わってくると思いますので、トレーナーの方とよく相談して、
成果の合意を取られるのが良いと思います。

投稿

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

+1

ASCII.jp:サンプルで見るシステム開発ドキュメントの作り方

上記リンク先のように、いろいろなドキュメントがありますが、
どれを書くかや細かい書式などは開発企業によっても違いますし、
ここでいちいち列挙しても多すぎて消化不良になると思います。


そこでドキュメントを思い切りざっくり分けると、こうなります。

1. 要件書、仕様書、設計書など
2. ユーザマニュアルなど
3. その他(テスト報告書など)

1は作る開発者が見るためのものです。(受託開発の場合、発注者も)
2は使うユーザが見るためのものです。(3は省略します)


2は誰でもソフトのマニュアルは見るだろうから、必要性は分かると思います。

1について、要件書はWhy(Want)、仕様書はWhat、設計書はHow、を示しています。
それ(プログラム)でしたいこと、それはどういうものか、それをどうやって作るのかです。

実務でこれらは基本設計書、詳細設計書などと、さらに細分化されますし、
もちろん書き方の技法も、UMLとかいろいろありますが、長くなるので省略します。


ドキュメントはコードと同じくらい労力がかかるので、
個人的には率直に言ってできれば書きたくないし、
じっさい形だけで不要な書類もあると思いますが、
しかしすべてが不要というわけでもないでしょう。

というのはドキュメントがないと、
最初に開発したメンバーと別の人が修正や保守をするとき困ります。
必要最小限のドキュメントはやはり必要だと思います。


まとめると、だれが何のために読むかを認識して書くと良いと思います。

もし、ドキュメントを書くのは退屈な雑務だとしか感じない場合、
たとえば自分がメンテナンスをするときに、どんなドキュメントが必要か、
ということを考えると、当事者意識や問題意識を持ちやすいと思います。

投稿

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

15分調べてもわからないことは、teratailで質問しよう!

  • ただいまの回答率 90.61%
  • 質問をまとめることで、思考を整理して素早く解決
  • テンプレート機能で、簡単に質問をまとめられる

関連した質問

同じタグがついた質問を見る

  • PHP

    19882questions

    PHPは、Webサイト構築に特化して開発されたプログラミング言語です。大きな特徴のひとつは、HTMLに直接プログラムを埋め込むことができるという点です。PHPを用いることで、HTMLを動的コンテンツとして出力できます。HTMLがそのままブラウザに表示されるのに対し、PHPプログラムはサーバ側で実行された結果がブラウザに表示されるため、PHPスクリプトは「サーバサイドスクリプト」と呼ばれています。