Category: :Category_Document, :CategoryDev, Team

マニュアル担当

コメント



マニュアルの作成方針について

開発日記/2004-08-24 から移動

余談ですが、特に使い勝手にかかわる部分(外部動作)について、とあるバージョンから有効になったり、無効になったりしたものはそれがわかる様に補足していただけると助かります。また、カスタマイズ要素のない部分(内部動作にかかわる部分)は(何も)書かずとも良いと思います。役割的には「ユーザー」マニュアルですから。 -- henoheno

  1. 外部動作の変更箇所はバージョンを併記する件について
    1. 情報を記述する意義はあると思います
    2. 記述を工夫しないと読みにくくなる懸念あり。もっともプラグインマニュアルに限ってはリファレンス的意味合いが強いため、影響は少ないと思います
    3. 現状の記述修正が必要。中途半端な記述を行うと誤解を生む可能性があるので、統一すべき。ただ、ここに労力を使うなら他のマニュアル整備に注ぐべきでは
    4. 今後のメンテは多少煩雑化する。管理やメンテの方針を明記する必要性があるのかもしれません
  2. 内部動作にかかわる部分を記述するかどうかについて
    1. 現状、プラグイン内設定は用途に関わらず一律挙げている
    2. 元々手間の掛かる項目にカスタマイズ要素かという判断(手間)が増える
      1. カスタマイズ要素かという判断が妥当かどうか明確な線引きがない
      2. 一律記述した方が記述漏れをチェックする時には楽
    3. ユーザーマニュアルと割り切って全く記述しない(削除する)方が良いかも
      1. スクリプトは用途に合わせてカスタマイズするもの、という個人的な思想の下、カスタマイズ可/不可の一定の目安としてdefineを挙げていますが、ユーザーには関係ない項目なので。


*1 おそらくhenohenoさんが言及されている箇所含む
*2 できればどこかで移動して論議したほうがいいようなきもするのですが

トップ   編集 凍結 差分 バックアップ 添付 複製 名前変更 リロード   新規 一覧 検索 最終更新   ヘルプ   最終更新のRSS
Last-modified: 2004-08-27 (金) 02:47:26
Site admin: PukiWiki Development Team

PukiWiki 1.5.3+ © 2001-2020 PukiWiki Development Team. Powered by PHP 5.6.40-0+deb8u12. HTML convert time: 0.213 sec.

OSDN