ドキュメント勉強会に参加してきました

以前から見ていた、Shin1x1さんのShin x blogでドキュメント勉強会開催を知り、興味があったので参加してきました。

私のドキュメントのイメージ

まだ、駆け出しのエンジニアだったころ、ドキュメントに対して持っていたイメージは、ひどいものでした。意味がない、信用できない、何のために書いているんだろう・・・etc.

あれから色々と経験を積んで、ドキュメントに対して一つ確実に言える事は、「読み手」があってのドキュメントだという事です。

読み手がどのような状況で利用するか、自分の頭で理解せずに、作り手の自己満足に終わったドキュメントほどヒドイものはありません。

私も過去に、作り手の自己満足としか思えないドキュメントを作っていた時期があります。そのような失敗から、「読み手」があってのドキュメントだという事を強く意識するようになりました。

そのような意識があれば、色々な失敗を防ぐ事ができると考えいるからです。

このような気持があったので、勉強会で色々な人のドキュメントの考えが聞けるのをすごく楽しみにしていました。

みなさんの発表内容と感じた事

「となりのドキュメント」と称して、発表者の方々が作成したドキュメントについて、発表されていました。みなさんのドキュメントに対する考え・気持ちがとても伝わってきました。


shin1x1さん
ソースはPCに伝えるもの、ドキュメントは人に伝えるもの
「伝える相手によって表現が違う」→「表現は技術で学べばよい」
すごく同意しました。

shinoiさん
ドキュメントをルール化して書いており、とても分かりやすかったです。ルールもシンプルに必要なものだけ定義されていたのでとても好感が持てました。

loungepさん
実践的な内容で、読む人がどんな人かターゲットを決めて書いているので、とても参考になりました。

msngさん
色々な場面で使われるドキュメントの役割の紹介が、とても分かりやすかったです。

slywalkerさん
wikiやRedmineなどのお話でした。私はドキュメントをwikiやRedmineで書いていないので、参考になりました。

whosaysniさん
reStrcuturedTextの紹介のお話でした。プレーンテキストでドキュメントを作成するので、差分が取りやすいという話に思わず「なるほど！」と思いました。

yabumaruさん
ウォーターフォールモデルのドキュメントのお話でした。今やっているプロジェクトがウォーターフォールモデルなので、とても参考になりました。


感激！
勉強会の途中で休憩があり、その時にみたらし団子のサービスがありました。とても美味しく頂きました。