人力検索はてな
モバイル版を表示しています。PC版はこちら
i-mobile

自作ソフトウェアのドキュメントを書こうと思っています。わかりやすいドキュメントを書く際に気をつけるべきこととしてはどんな物があるでしょうか?

●質問者: westfish
●カテゴリ:コンピュータ
✍キーワード:ソフトウェア ドキュメント 自作
○ 状態 :終了
└ 回答数 : 11/11件

▽最新の回答へ

[1]readmeのテンプレートを見る yamiwolf

動作確認環境、必要ランタイム、作者名、連絡先、簡単な使い方の説明は必ず必要でしょう

そうしなければ、利用者にドキュメントを読んでもらった場合、よくわからないと言ったことがよくあります。

また、ドキュメントのフォーマットは微妙に違いますが、だいたいテンプレートに沿って書いていている方が多数です

http://www.forest.impress.co.jp/article/2004/05/07/okiniiri.html

このようなソフトで必要事項を埋めていけばだいたいテンプレートに沿ったドキュメントが作れるので、とりあえず作ってみて参考にするのもありかと。


[2]更新の履歴が気になります takaramonob

長い間使用できるソフトを利用したいので、過去のバグや不具合修正の経緯が細かく明記してあるソフトは、その後も安心できそうな気がするので使ってみたいと思います。


[3]索引が必要 kurukuru-neko

どこに何がかいてあるかの大まかな索引が

あれば便利


[4]表示されるメッセージの一覧 shige_atenza

エラーメッセージやワーニングメッセージが出ると思います。

それぞれの意味と、どう対応すればいいのかの対応表があれば

いいかなって思います。


[5]ドキュメントとは m-nisi

利用者向けのドキュメントですか?

それとも開発者向けのドキュメントですか?

それによって違ってくると思いますが、

利用者向けのドキュメントなら他の人が書いてある事でいいと思います。

開発者向けのドキュメントなら、

関数一覧やフローチャートなど仕様書に近い形で残しておくと

他の人が開発しやすくなると思います。


[6]画面イメージ viba

やっぱりどんなドキュメントでも多くの画面イメージを

用い説明をしたほうがわかりやすいですよね

特に不特定多数に配布する場合、くだらない質問が来ても

困るので、それを防ぐためにも極力シロートに

わかりやすいようにするのがよいでしょう。

他の方の意見で、索引が必要とありますが

HTMLで作成することにより作成の手間は結構省けますし

オンラインマニュアルにすれば更新も楽です。

また、更新履歴などは上級者が必要としているため

TEXTなどで簡潔に表現することで十分でしょう


[7]設計書が必要では nagi0008

私は今までサーバの構築?運用を行っていたので、

ソフトウェアのドキュメントとは若干違うのですが、

共通点があればと思います。

まず、重要なのはどのような物を作るにしろ、

設計書が必要かと思われます。

<必要と思われるドキュメント>

・基本設計書

・詳細設計書

<記述内容>

・基本設計書には開発ソフトは何を使用したのか。

・どういう理由で今の構成(文法)を使用したか。

・仕様変更等がかかった際にわかりやすくするための変更履歴を記述する箇所を設ける

また、ソースコードの管理についても必須と思われます。

上記で記述している変更履歴のことと多少重なってしまうかもですが、

・どの部分をいつ変更したか。

・元の記述内容と、変更後の記述内容が比較できれば尚良い

私がぱっと書ける範囲ではこの程度ですが、

他にも業務として開発を経験されている方であれば、

そちらの人のを参考にした方がいいかも知れませんね。


[8]>5 想定する読み手次第というのに同感 gakuyo

想定する読み手次第というのに同感です。

私が本を書く際にも、とにかく、これを間違うとどうしようもなくなります。もちろん、あらゆる読者に合わせることはできないので、想定外の方については「ゴメンナサイ」するしかないのですけれど。

で、私がシェアウェアのソフトを使っていて思うのは、とにかくドキュメント・マニュアルがわかりにくい(私は、ソフトは使えるだけで、書いたことがあるのはBasicというレベルです)。というわけで、何がわかりにくかったか、参考になればと思い列挙しておきます。

探したいもの(機能・設定など)がみつからない。

これは、索引があってもうまくいかないことが多いです。こういうことができないかなぁ……と思っても、それを示す単語がわからない場合、索引て機能しませんから。

操作で迷ったときに困る。

こういうときはこう、こういうときはこう、と設定を変えるような場面で指示が明確でないと困ります。

あとは、用語がわからないことが多いですねぇ(これは勉強不足といわれたらしかたがないですけれど)。


[9]使い方が感覚的に理解できる具体例 nandedarou

機能の網羅的な説明の他に、

ソフトの使い方が短時間で感覚的に理解できるように

具体例を用いての説明が欲しい。

こういうのチュートリアルっていいますよね?

でも、チュートリアルって言葉自体があまりなじみがないので

言葉も分かりやすくすべき。


[10]>5 ターゲットはどこか? paihu

利用者向けか,開発者向けか

という違いもありますが利用者向けと考えるとして,素人から玄人までいるので,どのあたりに焦点を当てるかだと思います.

ほかの人も書いてますが,更新履歴を気にするレベルの人もいれば,画面のスクリーンショット等でわかりやすい使い方を示して欲しい人もいますし.

どれも洩れなくカバーしようとする(それが理想かもしれませんが)と相当な労力が必要になりますので,ある程度絞ってドキュメントを書くのが良いと思います.

どこを焦点にするかは,ソフトウェアをどんな人に使ってもらいたいのかということですね.


[11]本当にいいソフトとは nandedarou

本当にいいソフトとは

マニュアルがなくても使い方がわかるソフトだと思います。

※質問の趣旨から外れてごめんなさい。m(__)m

関連質問


●質問をもっと探す●



0.人力検索はてなトップ
8.このページを友達に紹介
9.このページの先頭へ
対応機種一覧
お問い合わせ
ヘルプ/お知らせ
ログイン
無料ユーザー登録
はてなトップ