マニュアル執筆中(その11)

OOoBaseRTCの機能を増やしたのと、Install.batの内容を少し修正したぐらいです。



OpenOfficeを操作するRTC群のマニュアル
MSOfficeを操作するRTC群のマニュアル




機能を増やしましたけどまだ不足している感じですね。
何かいいアイデアのある人は教えて頂けるとありがたいです。



突然ですが、プロジェクトのページとマニュアルの書き方を考えてみた。
個人的な見解なので参考にはしないことをお勧めします。

まずプロジェクトのページですが、一番重要なのはソフトウェアとマニュアルの入手先を明確に書くことだと思います。例えばGitHubを使っている人が多いと思いますが、使ったことない人間からするとどこからダウンロードできるのか分かりづらいので注意が必要だとは思います。

次にそのソフトウェアを使うことで何ができるのか、何を作ったのかをはっきりさせること。
動画や画像があればわかりやすいかもしれないです。
データポートの詳細などはマニュアルに書けばいいので、各RTCがどのような役割なのか概要だけ書くことになると思います。

ただ作った物次第では説明が難しい場合もあるので、その場合は実用的な例を書くとわかりやすくなるのではないでしょうか？


全体的な流れとしては、

1. 概要
2. 特徴
3. 仕様
4. 各コンポーネントの概要
5. ソースコード、マニュアルの入手方法
6. ライセンス
7. 必要であれば、動画・更新履歴・謝辞・スライド・連絡先等

こういう書き方をしてる人が多い気がする。

とりあえず、1、2、5さえ書いておけば見ている人が困ることは少ないのではないでしょうか？



次にマニュアルです。
マニュアルを読むことでソフトウェアの動作を再現できるのが第一でしょう。
インストールの方法は特に穴のないように書く必要があると思います。
マイコン等を使っている場合は回路図も書く必要があるのですが、その回路がどのような動作をするのかが詳しく書いてあるとわかりやすいと思います。

とりあえず使いこなす以前に基本的な動作ができることが重要だと思うので、使用方法はわかりやすく書く必要があります。
詳しく書くよりも、わかりやすく書くほうが重要だと思います。
雑多な内容ではなく、「この流れの通りにやればこういうことができる」という事が書いてあれば動作を再現しやすいのではないでしょうか？



全体的流れはマニュアルによって異なるので一概にこれというのはないのですが、概要、仕様を最初に書いている人が多いような感じはします。








これだけマニュアルの書き方について分析しておきながら、自分のマニュアルはなんであんなにあれなのかと思い始めました。分析が全く反映されてません。

自分のマニュアルの参考になるかと思って過去のコンテストの作品のプロジェクト、マニュアルを読んでみてどうしたら自分がわかりやすいかを上に書いてみたのですが、自分のマニュアルの悪いところはよくわからんのですよ。
とりあえず悪いことしかわからなくて、具体的にどこが悪いのかよくわからないです。
マニュアルってひょっとして人に書いてもらった方がわかりやすいものが書けるのではないでしょうか？少なくともその書いた人は動作を再現できてるわけですからね。









にほんブログ村のロボットのカテゴリから
全然人が来ない・・・