アカウント名:
パスワード:
確かにドキュメントは大事ですね。分かっている人が、分かっている人向けに書いたドキュメントとか見るとうんざりすることも多いです。分かっている人しか見ないなら別にいいんですけど・・・。
特にルールの無い雑な会社で、ドキュメント作って!と丸投げされて悩みつつ書いてたことがありますが、どこに基準を置くかは難しいです。
「ほんとーに何も分からない人」を想定すると、それこそ操作方法やコマンドを一言一句書かないといけないんでしょうが、そうするとOSやらブラウザやらをバージョンアップしただけで理解できなくなってしまいかねません。 ちゃんと改版されるなら別にいいんですが、そういう会社では基本放置されがちなので、メンテは期待できません。
分かってる人に読ませる前提なら、例えばFTPサーバーの情報はこれですんで、FTPで接続してください、と書いておけば済みます。 読む側としても、自分の使い慣れたFTPクライアントなりでやれば良くて、面倒がありません。 余計な情報が含まれない分、どこまでが必要な情報(orルール)でどこからがそれ以外か?と悩む必要もなく、変更もしやすいです。
妥協点として、必要な情報に加えて例を併記する、という手もあり概ねこの方針で進めましたが、これはこれで同じ情報を二重・三重に記載することになり、手間は増えるわ修正ミスは増えるわで一長一短がありました。
個人的には、会社としてある程度最低限のスキルの基準を設けて、これが分からない人材が読むことはない、とか整理してもらいたいものです。 # 自社で人材を抱えない/教育しないで、なんでも派遣任せにする昨今の風潮では難しいでしょうがorz
作業を任せる対象の想定は本当に難しいですね。
以前、
・A、Bの2台のサーバの両方で・X、Yの2つの処理を実行する
と書いた手順書を渡したら、AでXのみを、BでYのみを実行されてトラブった経験があります。実行担当者(UNIXサーバでroot権限での管理経験(年単位)がある)に確認したところ、「AとB」「XとY」と目に入ったので1対1の作業だと勘違いした、とのことで、最終的には
・AでXとYを実行する・BでXとYを実行する
と書かなかった私が悪い、という結論に落ち着きました。
それ以降、どんな簡単なドキュメントでも、それを扱う可能性のある全員との読み合わせを必ず行い、こちらの意図を説明するようにしています。えらく大変ですけど、トラブるよりはマシと考えています。
# 実体験なのでさすがにACで
URIとID、パスワードがあれば、トレーニングを受けたあるべき知識のある人なら接続できるんじゃないの?
知識のないエンドユーザー相手ならわかるけど・・・。それとも、コの業界って、トレーニングもなしに保守の現場に放り込まれるの??
同意。SFTPやあれやこれ細かい設定が必要な環境ならまだしも、FTPを普通に使うだけで、いちいち細かいことまで教えられないと駄目ってどうかと思う。
例えば、ありがちな文字化けとかのトラブルだって、このサーバーの文字コードはEUC-JPです、とだけ伝えれば本来十分なはずでしょ? いちいちマニュアルに、FFFTPの使い方から、文字化けしないようにここはこのコンボボックスからEUC-JPを選んでください、程度まで書かなきゃいけないの? プロバイダーが会員に説明するようなマニュアルならともかく、データセンターやらでシステムの保守管理に使うようなマニュアルの話なのに?
そんなレベルの素人を送り込むな、教育してからにしろ、新たに雇うならそんな奴雇うなと声を大にして言いたい。 コストかけたくない?そんな会社、大きなトラブルでも起こして倒産しちまえ!
それを通り一片の教育しかしてないオペレータに要求する?まさに正気を疑うとしか。
そもそも、そんな人を配置することこそが、まさに正気を疑う行為だとしか言えませんね。 ど素人を集めてなんとか出来るほど保守は甘くないですよ。
逆だと思いますねあまり具体的なことを書きすぎるとあとで面倒なことが起きます指定ツールが公開止めたりしたら困るでしょうできるだけ抽象的に汎用性があったほうが良いですよぎちぎちに書いたドキュメントなどはちょっと手順が変更になっただけで使い物にならなくなるというのが良くあります
より多くのコメントがこの議論にあるかもしれませんが、JavaScriptが有効ではない環境を使用している場合、クラシックなコメントシステム(D1)に設定を変更する必要があります。
Stay hungry, Stay foolish. -- Steven Paul Jobs
複雑化 (スコア:2)
確かにドキュメントは大事ですね。
分かっている人が、分かっている人向けに書いたドキュメントとか見るとうんざりすることも多いです。
分かっている人しか見ないなら別にいいんですけど・・・。
分からない人向けドキュメントは難しい (スコア:0)
特にルールの無い雑な会社で、ドキュメント作って!と丸投げされて悩みつつ書いてたことがありますが、どこに基準を置くかは難しいです。
「ほんとーに何も分からない人」を想定すると、それこそ操作方法やコマンドを一言一句書かないといけないんでしょうが、そうするとOSやらブラウザやらをバージョンアップしただけで理解できなくなってしまいかねません。
ちゃんと改版されるなら別にいいんですが、そういう会社では基本放置されがちなので、メンテは期待できません。
分かってる人に読ませる前提なら、例えばFTPサーバーの情報はこれですんで、FTPで接続してください、と書いておけば済みます。
読む側としても、自分の使い慣れたFTPクライアントなりでやれば良くて、面倒がありません。
余計な情報が含まれない分、どこまでが必要な情報(orルール)でどこからがそれ以外か?と悩む必要もなく、変更もしやすいです。
妥協点として、必要な情報に加えて例を併記する、という手もあり概ねこの方針で進めましたが、これはこれで同じ情報を二重・三重に記載することになり、手間は増えるわ修正ミスは増えるわで一長一短がありました。
個人的には、会社としてある程度最低限のスキルの基準を設けて、これが分からない人材が読むことはない、とか整理してもらいたいものです。
# 自社で人材を抱えない/教育しないで、なんでも派遣任せにする昨今の風潮では難しいでしょうがorz
Re:分からない人向けドキュメントは難しい (スコア:1)
作業を任せる対象の想定は本当に難しいですね。
以前、
・A、Bの2台のサーバの両方で
・X、Yの2つの処理を実行する
と書いた手順書を渡したら、AでXのみを、BでYのみを実行されてトラブった経験があります。
実行担当者(UNIXサーバでroot権限での管理経験(年単位)がある)に確認したところ、
「AとB」「XとY」と目に入ったので1対1の作業だと勘違いした、とのことで、最終的には
・AでXとYを実行する
・BでXとYを実行する
と書かなかった私が悪い、という結論に落ち着きました。
それ以降、どんな簡単なドキュメントでも、それを扱う可能性のある全員との読み合わせを
必ず行い、こちらの意図を説明するようにしています。えらく大変ですけど、トラブるよりは
マシと考えています。
# 実体験なのでさすがにACで
Re: (スコア:0)
> 読む側としても、自分の使い慣れたFTPクライアントなりでやれば良くて、面倒がありません。
最悪です。
世の中にあるすべてのFTPクライアントがRFCの機能をすべて網羅していてバグがなければそれでいいのかもしれませんが、んなわけないので、あなたのドキュメントはあなたの仮定した(そして操作者は知らない)FTPクライアントを前提とした使えないドキュメントにしかなりません。
きちんと動作検証したFTPクライアントについて逐一操作を記述するか、最悪Windows標準のFTP.exeコマンドに投入するコマンドをベタ書きするかしてください。
Re: (スコア:0)
URIとID、パスワードがあれば、トレーニングを受けたあるべき知識のある人なら接続できるんじゃないの?
知識のないエンドユーザー相手ならわかるけど・・・。
それとも、コの業界って、トレーニングもなしに保守の現場に放り込まれるの??
Re: (スコア:0)
同意。SFTPやあれやこれ細かい設定が必要な環境ならまだしも、FTPを普通に使うだけで、いちいち細かいことまで教えられないと駄目ってどうかと思う。
例えば、ありがちな文字化けとかのトラブルだって、このサーバーの文字コードはEUC-JPです、とだけ伝えれば本来十分なはずでしょ?
いちいちマニュアルに、FFFTPの使い方から、文字化けしないようにここはこのコンボボックスからEUC-JPを選んでください、程度まで書かなきゃいけないの?
プロバイダーが会員に説明するようなマニュアルならともかく、データセンターやらでシステムの保守管理に使うようなマニュアルの話なのに?
そんなレベルの素人を送り込むな、教育してからにしろ、新たに雇うならそんな奴雇うなと声を大にして言いたい。
コストかけたくない?そんな会社、大きなトラブルでも起こして倒産しちまえ!
Re: (スコア:0)
マジありえません。というかFTPなんて前世紀に捨ててくるべきウンコです。ftp.exeでさえロクにRFCに従ってないバグ満載アプリなんですが、時間の限られたメンテ時にいちいちMSDN引いて障害の切り分けさせるんですか?それを通り一片の教育しかしてないオペレータに要求する?まさに正気を疑うとしか。
Re: (スコア:0)
それを通り一片の教育しかしてないオペレータに要求する?まさに正気を疑うとしか。
そもそも、そんな人を配置することこそが、まさに正気を疑う行為だとしか言えませんね。
ど素人を集めてなんとか出来るほど保守は甘くないですよ。
Re: (スコア:0)
逆だと思いますね
あまり具体的なことを書きすぎるとあとで面倒なことが起きます
指定ツールが公開止めたりしたら困るでしょう
できるだけ抽象的に汎用性があったほうが良いですよ
ぎちぎちに書いたドキュメントなどはちょっと手順が変更になっただけで使い物にならなくなるというのが良くあります