利用者向けか,開発者向けか
という違いもありますが利用者向けと考えるとして,素人から玄人までいるので,どのあたりに焦点を当てるかだと思います.
ほかの人も書いてますが,更新履歴を気にするレベルの人もいれば,画面のスクリーンショット等でわかりやすい使い方を示して欲しい人もいますし.
どれも洩れなくカバーしようとする(それが理想かもしれませんが)と相当な労力が必要になりますので,ある程度絞ってドキュメントを書くのが良いと思います.
どこを焦点にするかは,ソフトウェアをどんな人に使ってもらいたいのかということですね.
機能の網羅的な説明の他に、
ソフトの使い方が短時間で感覚的に理解できるように
具体例を用いての説明が欲しい。
こういうのチュートリアルっていいますよね?
でも、チュートリアルって言葉自体があまりなじみがないので
言葉も分かりやすくすべき。
想定する読み手次第というのに同感です。
私が本を書く際にも、とにかく、これを間違うとどうしようもなくなります。もちろん、あらゆる読者に合わせることはできないので、想定外の方については「ゴメンナサイ」するしかないのですけれど。
で、私がシェアウェアのソフトを使っていて思うのは、とにかくドキュメント・マニュアルがわかりにくい(私は、ソフトは使えるだけで、書いたことがあるのはBasicというレベルです)。というわけで、何がわかりにくかったか、参考になればと思い列挙しておきます。
探したいもの(機能・設定など)がみつからない。
これは、索引があってもうまくいかないことが多いです。こういうことができないかなぁ……と思っても、それを示す単語がわからない場合、索引て機能しませんから。
操作で迷ったときに困る。
こういうときはこう、こういうときはこう、と設定を変えるような場面で指示が明確でないと困ります。
あとは、用語がわからないことが多いですねぇ(これは勉強不足といわれたらしかたがないですけれど)。
私は今までサーバの構築~運用を行っていたので、
ソフトウェアのドキュメントとは若干違うのですが、
共通点があればと思います。
まず、重要なのはどのような物を作るにしろ、
設計書が必要かと思われます。
<必要と思われるドキュメント>
・基本設計書
・詳細設計書
<記述内容>
・基本設計書には開発ソフトは何を使用したのか。
・どういう理由で今の構成(文法)を使用したか。
・仕様変更等がかかった際にわかりやすくするための変更履歴を記述する箇所を設ける
また、ソースコードの管理についても必須と思われます。
上記で記述している変更履歴のことと多少重なってしまうかもですが、
・どの部分をいつ変更したか。
・元の記述内容と、変更後の記述内容が比較できれば尚良い
私がぱっと書ける範囲ではこの程度ですが、
他にも業務として開発を経験されている方であれば、
そちらの人のを参考にした方がいいかも知れませんね。
やっぱりどんなドキュメントでも多くの画面イメージを
用い説明をしたほうがわかりやすいですよね
特に不特定多数に配布する場合、くだらない質問が来ても
困るので、それを防ぐためにも極力シロートに
わかりやすいようにするのがよいでしょう。
他の方の意見で、索引が必要とありますが
HTMLで作成することにより作成の手間は結構省けますし
オンラインマニュアルにすれば更新も楽です。
また、更新履歴などは上級者が必要としているため
TEXTなどで簡潔に表現することで十分でしょう
利用者向けのドキュメントですか?
それとも開発者向けのドキュメントですか?
それによって違ってくると思いますが、
利用者向けのドキュメントなら他の人が書いてある事でいいと思います。
開発者向けのドキュメントなら、
関数一覧やフローチャートなど仕様書に近い形で残しておくと
他の人が開発しやすくなると思います。
エラーメッセージやワーニングメッセージが出ると思います。
それぞれの意味と、どう対応すればいいのかの対応表があれば
いいかなって思います。
どこに何がかいてあるかの大まかな索引が
あれば便利
長い間使用できるソフトを利用したいので、過去のバグや不具合修正の経緯が細かく明記してあるソフトは、その後も安心できそうな気がするので使ってみたいと思います。
動作確認環境、必要ランタイム、作者名、連絡先、簡単な使い方の説明は必ず必要でしょう
そうしなければ、利用者にドキュメントを読んでもらった場合、よくわからないと言ったことがよくあります。
また、ドキュメントのフォーマットは微妙に違いますが、だいたいテンプレートに沿って書いていている方が多数です
http://www.forest.impress.co.jp/article/2004/05/07/okiniiri.html
このようなソフトで必要事項を埋めていけばだいたいテンプレートに沿ったドキュメントが作れるので、とりあえず作ってみて参考にするのもありかと。
本当にいいソフトとは
マニュアルがなくても使い方がわかるソフトだと思います。
※質問の趣旨から外れてごめんなさい。m(__)m