技術ドキュメントに何を書くか

テクニカルなドキュメントを書くなら何を書くべきか、という記事。
Writing great documentation: what to write.

  • チュートリアルを作れ
    • 素早いのを:使い手が20分以内に何かしら達成感を得られるように
    • 簡単なのを:Foolproofな内容にしておく
    • ただし能力不十分な人は挫折させるようにする
    • その技術の大体の「感じ」が掴めるように、いろんな側面を見せる
  • トピックガイドを作れ
    • よくあるユースケースを網羅する
    • これだけ見れば使い方が分かるようにする
  • リファレンスを作れ
    • トピックガイドには些末すぎる引数や動作の詳細などを載せる
    • リファレンスをチュートリアルやトピックガイドの代わりにするな!
  • Javadoc的なのは使うな
    • 手で書き、手で編集して、手で整理したドキュメントには勝てない

元記事でも言われてるが、トピックガイドというのは公式ドキュメントに含まれてることが少ない気がする。そういえば一番役に立つのは全体を見渡せるし具体例にも触れられるトピックガイドなのかも。たとえばプログラミング言語やフレームワークなどの場合、いくらリファレンスが充実していても、トピックガイドがないと膨大なモジュールのうちどれを使えばいいのかが分からなかったりする。

ドキュメントの自動生成については元記事と同意しかねるかな。リファレンスなら自動生成でいいでしょと思う。残りの部分はそもそも手で書くしかないわけだし。

Djangoのドキュメントが優れてるらしい。僕がこれまでに見た中で優れたドキュメントといえば…。うーむ。何があったかな。The Subversion Book?CodeIgniterのドキュメントも良かったと思う。

Categories: HowTo's, Tips and Tricks | Tagged | Leave a comment

Flash CS5で何が新しいのか

Flash CS5がリリースされたということで。

  • ビデオにキューポイントを設定してASのイベントを発火させられる
  • Flex Builderのスゴイ 版Flash Builderがついてる
  • Flash内のASエディタも補完とかが良くなった
  • 物理エンジンが洗練された
  • イラレやInDesignで作られたテキストを持ち込みやすくなった
  • フォトショやイラレで作ったグラフィックを持ち込んでインタラクティブにできる(Flash Catalyst)
  • 単一の.flaだけじゃなく中身が独立したパックとして保存できる

物理エンジンってついてたんや。

Flash内のASエディタはCS3では割と使いにくいので是非とも新しいのを使ってみたい。

ソース:Flash CS5 First Look: Adobe Drops a Hefty Update Into Stormy Waters| Webmonkey | Wired.com.

ちなみにInDesign CS5ではe-bookを作りやすくなったらしい。

InDesign CS5 introduces interactivity to page layout – Yahoo! News

Categories: Ideas and Products | Tagged | Leave a comment

ウガンダでは多くの子どもが生贄として死んでいる

非常に衝撃的な記事を読んだので反射的にポスト。

ウガンダで子どもの生贄の現状が明らかに
BBC News – Newsnight – Witch-doctors reveal extent of child sacrifice in Uganda

A BBC investigation into human sacrifice in Uganda has heard first-hand accounts which suggest ritual killings of children may be more common than authorities have acknowledged.

[... A] former witch-doctor who now campaigns to end child sacrifice confessed for the first time to having murdered about 70 people, including his own son.

ウガンダではこれまで知られていた以上に多くの子ども達が生贄として殺されているらしいことが、BBCの調査により分かった。

現在は子供の人身供犠反対運動を行っている元ウィッチ・ドクターは、自分自身の子どもを含めこれまでにおよそ70人を殺害していることを明かした。

話はさらに現実味を増す。

“They capture other people’s children. They bring the heart and the blood directly here to take to the spirits… They bring them in small tins [...],” he said.

Asked how often clients brought blood and body parts, the witch-doctor said they came “on average three times a week – with all that the spirits demand from them.”

「患者たちは子どもをさらって、心臓などを小さな缶に入れて持ってきます。」
[...]
どれくらいの頻度で血液や臓物などが持ち込まれるのかとの質問には、「平均して週三回ほどです。持ち込まれるのは精霊が求めたもの全てです。」と答えた。

なんという…。生贄なんてインディ・ジョーンズの世界でしか知らなかっただけに、これはショッキングだ。そりゃあ世界のどこかでそんなことが起こってるらしい、ぐらいは想像できるが、こんな風に言われると「そんなに!?」と思ってしまう。

さらに記事内では、この証言者が反対運動で回っただけでも2400人の呪術師がいる事、全国レベルの呪術師連合があって末端の呪術師の儲けは連合の偉いさんに上納するシステムになっている事などが明かされている。

平均して週三回とはにわかには信じがたい数だ。2400人の呪術師に週イチで臓物が持ち込まれるとしても年間約12万人の子どもたちが体の一部を切り取られていて、おそらくその大部分が死んでいることになる。ほんまか。しかも2009年に警察で生贄殺人として調査したのがたったの26件だというから、警察などほとんど役に立っていないようだ。

呪術治療なりカウンセリングなどの料金は一回あたり260USDほどだというのも驚きだ。ウガンダの推定一人当たりGDP(2008)が1300USDだから、その比で日本円にすると60万円以上と滅茶苦茶に高い。それを吸い取る連合の後ろには大きなヤクザ組織のようなものがあるような気がする。

想像だが、患者は強制されて子どもを殺すわけではないんだろうな。効果があると信じてしまうんだろう。寝が深そうな問題だ。素人考えではやはり教育によって改善すべきことのような気がするが、どうなんだろうか。

Categories: Whatnot | Tagged | 1 Comment

RailsをApache+FCGIでサブディレクトリで動かす方法

config/environment.rbにて

config.action_controller.relative_url_root = "/subdir"

via RailsBaseURI not working with Rails 2.2.2 routes? – Phusion Passenger Discussions | Google グループ.

Categories: HowTo's, Tips and Tricks | Tagged , | Leave a comment

Heartbeatの使い方

こないだ、バイトでHeartbeatを実験セットアップしました。

しかしHeartbeatの公式ドキュメントは情報が散り放題リンク切れ放題で悲惨なものでしたので、耐えきれず勝手にGoogle Docsにまとめてしまいました。せっかくなので公開しておきます。

Heartbeatの使い方

主な内容は

  • Heartbeatとは何なのか、何ができるのか
  • 用語の説明
  • インストールと設定手順
  • 設定項目や付属プログラムについて
  • 設定ファイルの例

となっています。

整形してどこかの公開Wikiに上げたいけど、面倒くさいなぁ…。

Categories: HowTo's, Tips and Tricks | Tagged | Leave a comment