nDiki : reStructuredText

プロジェクトの後半で納品用ドキュメントの整備を始めるのだが、その時はたいがいもう切羽詰りはじめていて構成やら体裁やらマネジメントやらを工夫する余力が無かったりする。ついつい(次回は改良しようと思っていつも思っている)前回のプロジェクトの手法を踏襲してしまいがちだ。ともすれば劣化コピーになりかねない。

やはり、忙しくても日頃からの改善は重要である。

最近はアジェンダ・議事録・開発メモなどを、積極的に Wiki や Subversion で共有するようにし、その点では以前より改善してきている。

今後はさらに、出荷ドキュメントのレビュープロセスなどを確立し品質を高めていきたいところである。現状でもチームメンバでのピアデスクチェックやパスアランドを非形式的に行っているのだが、「チェックの程度」やその後の「修正」および「修正の確認」については、まだなんとなくやったかなという具合。この辺りを工夫したい。

先月発売されていて気になっていた「開発の現場 Vol.003」に、何かヒントがあるかなと思って買ってみた。

開発の現場 Vol.003 効率UP&スキルUP ドキュメンテーション大全

パラパラと見た感じではテクニカルライティングの話はあまりなく、主にソフトウェア開発における中間成果物としてのドキュメントや開発者間ドキュメントをどうとりまとめていくかという話が中心のよう。 Wiki による開発資料のライトな共有など、うちのチームでも進めている話など。

「(最初から)完全なドキュメントを書こうとしない」というのはもっとも。状況はほとんどの場合変わるし、最初の段階では未確定の部分も多い。だからといって、いつまでたっても手元で温めていてもしょうがない。

技術的な話では Perl の Pod を活用しようという話。 Perl 以外の言語のコメント中に Pod 形式でドキュメントを書こうという提案や、Apache で動的に Pod ドキュメントを整形しようという話とか。

テキストフォーマットとしての Pod は =over / =item / =back によるリスト表現など、最近のフォーマットに比べてすごく読み易いわけではないが、たしかに他の言語のコメントに埋め込んでおいて処理するのは、標準の Pod 関連のモジュールでできるな。

自分も Pod でドキュメントを書くけれど、(Perl 以外は) 個人的には reStructuredText にしたいと考えている。ただ Pod みたいに他のテキストの一部に埋め込んでその部分のみ処理する記法およびツールがが標準の reStructuredText / Docutils には見当らない。実はどっかにあるのだろうか。

[ 読書ノート ]

[ permalink ]

[ 2月15日全て ]

2006年3月8日 (水)

Mule-UCS の設定

reStructuredText では表を作る時は文字数で桁揃えして、表セルを表現していく。 ASCII 文字などフォント幅がいわゆる半角幅であるものだけならば、良いのだが全角幅の文字がある場合はちょっと厄介である。

文字数的には1文字なのだが、テキストファイル上では2文字分の幅を取るので見た目上桁が揃わなくなってしまう。というかそれを忘れて桁を揃えておくと、パーサに怒られる。

このためにパッチがあったり、Docutil 0.4 ではこの対策がほどこされたりしている(不完全であるが)。

さらに厄介なのが Unicode 変換がからむところで、 Emacs + Mule-UCS ではいくつかの(いわゆる)全角文字は UTF-8 で保存すると違う文字に変換されてしまい、これまた Docutils のパーサに、桁があっていないと怒られることになる。

できるだけ全角文字はそのままにしておくということで、以下の設定を追加しておいた。

 (require 'un-define)
 (un-define-change-charset-order
  (append '(ascii japanese-jisx0208)
          unicode-basic-translation-charset-order-list))

またバックスラシュと円記号の方も混乱が少ないように

 (require 'un-supple)
 (un-supple-enable 'windows)

を追加してく。

[ permalink ]

[ 3月8日全て ]

2006年3月31日 (金)

GTD 参照資料ファイル置場として howm を使い始めてみた

Life Hacks PRESSの巻末「執筆陣に聞きました!」で、角谷信太郎氏が、howm でメモをしていると述べていた。

以前話題なった時にも気になったんだけれど、その時は emacs-wiki を使っていたこともあって手を出しそびれてしまった。

howm は検索を中心としたリンク機能を持つメモツール。名前を指定せずにちょっとしたメモを作成し、後で探し出すことできる。

GTD で参照資料扱いとするメモをどこに保存しておこうかと思案していたのだが、丁度よさそうだ。

ソフトウェアインストール時の作業履歴やら、ちょっとした下書きやらのファイルも散在して後で扱いに困っていたのだが、これらもまとめて放り込んでおける。しばらく使い込んでカスタマイズしたりして、自分流のスタイルを模索してみることにしよう。

howm 自体はほとんど書式というものがない。自分の好きな形式で自由に書くことができる。自分は reStructuredText か WiKicker 形式で書くことになるかな。

その辺も含めていろいろ遊んでみよう。

[ permalink ]

[ 3月31日全て ]

2006年5月5日 (金)

ビジネスメールガイドライン案

以前メールによる社内コミュニケーションの問題について書いて以来、いろいろと考えてみている。

そんな中、東洋経済新報社の「Think! SPRING 2006 No.17 超ロジカルシンキング」の中に参考になる記事を発見。照屋華子氏の「ロジカル・ライティング - 論理的に考え、伝えるための3つの鍵を身につける」という記事だ。

すべてのビジネス・コミュニケーションは「伝え手」「受け手」「テーマ」「答え」「期待する反応」という5つの基本要素で成り立っている。-- Think! SPRING 2006 No.17 p.43

おお、ちょうどこういう切り口を探していたところだったんだ。電子メールによるコミュニケーションも全く同じ枠組みである。記事の中ではロジカルシンキングをコミュニケーションで生かすという話題を中心に展開しているが、十分メールの書き方に通じるものがある。

この記事と、さらにちょっと前に買った「SEの実力を磨く究極仕事術」のメール術の章を参考にガイドライン案のスケルトンを作ってみた。

感情論は今回は置いておいて、情報共有・課題共有・リクエストの明確化・処理促進をポイントに列挙。それから署名その他、一般的な話もいまのところ省略。

ポイントを列挙しただけなので、他人にもわかる形にはなっていない。

まずは自分自身に適用して、整理していってみることにする。

1. 考える

【伝え手】伝え手は誰? (自分)
【受け手】受け手は誰?
【テーマ】テーマは何? 問いの形で。メールのテーマは1つに絞られているか?
【答え】テーマに対する答え(テーマに対する説明)は何?
【期待する反応】受け手に期待する反応は何?
- 誰に、いつまでに、何をどうして欲しい?
コミュニケーション手段としてメールは適切?

2. メールを書く

 ○○様へ                     # 受け手

 △△の××(自分)です。       # 伝え手

 テーマ
 ******
 コミュニケーション設定

 ○○の結論                   # 答え (結論)
 ==========
 ...

 (ここまででポイントを言いきる。)

 具体的な内容                 # 答え (詳細)
 ============

 項目1
 -----
 ....

 - リスト項目
 - リスト項目

 項目2
 -----
 ...

 - リスト項目
 - リスト項目

サブジェクトを書く

見ただけでわかるようにする
- □ 具体的に書く

導入部を書く

コミュニケーション設定を行う。

□ 冒頭に宛先【受け手】を明記する。(誰に読んで欲しいのか? 他に誰に送られているのか?)
□ 次に発信者【伝え手】を明記する。(From: フィールドに頼らず書く → 印刷・コピー用)
□ 【テーマ】を書く。
□ (オプション)【テーマ】の経緯・背景を書く。(「なぜこのテーマのメールがくるの?」)
□ (オプション)なぜこの【伝え手】からなのかを書く。(←「なぜあなたからリクエストされるの?」)
□ 【期待する反応】を明記する。
- □ 「誰が」「何を」「いつまでに」「どのような品質で」して欲しいのかを書く? (← 「で何をして欲しいの?」)
- □ 反応のメリットを書く (←「なぜこの反応をとらなければならないの?」)
- NG 「ご意見があればお願いします」 → ない場合は?
- NG 「どちらが良いと思いますか?」 → 意見として? 決定として?
- NG 「ご検討ください」→ 検討した後どうして欲しいのか?
□ (オプション)なぜこの【受け手】に読んでもらいたいのかを書く (←「何で自分なの?」)
□ 特記事項があれば書く
- □ 答えの情報源など

答え (結論)

結論を書く。

□ 詳細まで読まなくても済むようにする。
- NG 「以下のように……」 → 要旨を書く
- NG 「添付ファイルの通り」 → 要旨を書く

答え (詳細)

根拠・資料などを書く。

□ 受け手から見て必要十分な情報を書く
- NG 「添付ファイルの通り」 → 要旨を書く
□ 受け手が読みやすいように書く
- □ リスト化する

全般

□ 具体的に
- NG 「来週までに……」 → 「×月×日までに……」
- NG 「先日の……」 → 「×月×日の……」
- NG 「この間の……」 → 「×月×日の……」
- 説明は肯定形で書く (否定形だと具体的に何なのかわからない)
□ 論理的に
- □ 構造化する
- □ リスト化する (箇条書き化する)
□ 受け手が読みやすいように
- □ フォーマットを工夫する (ソフトウェア技術者間なら reStructuredText がお薦め)

3. 送信する

□ 送信する前に見直す
- □ typo チェック
- □ スペルチェッカ通す

A. メールを受信した時

まず返信する

どれか

リクエストを「受ける」 / 返信で処理する (意思決定を返すなど)
リクエストを「断わる」
「別の提案をする」
明確化の質問をする

メールでは不適当と思ったらコミュニケーション手段を直接 / 電話に切り換える。

B. 返信する時

サブジェクト

□ テーマが変わったら書き換える

[ permalink ]

[ 5月5日全て ]

2009年11月9日 (月)

今日のさえずり: たまにオッサンみたいな驚き方する

2009年11月09日

08:18 ベンザブロック L服用。 [mb]
09:27 駅が混沌としている。 [mb]
09:32 山手線運転再開しているのか。京浜東北線混雑にはもう影響しないかな? [mb]
09:40 京浜東北線田町駅で山手線内回りと並走。山手線も空いている。 [mb]
12:39 ベンザブロックL服用。
12:42 「たまにオッサンみたいな驚き方する」って言われてしまった。
12:50 フグ田マスオ28歳。 RT @wtnabe: @Naney そういうときのために「マスオさんが驚いたときのマネ」を体得しとくといいですよ。
14:08 うーん、喉がイガイガするので飴買ってくる。
14:15 プロポリスのど飴にした。プロポリス成分はきっと気休め程度しか入ってないんだろうな。 [mb]
14:23 UHA味覚糖のプロラボプロポリスのど飴が予想以上にビリビリくる。刺激的で赤面。
14:27 @Michiaki 初めて舐めたんですが、これって効きますか?
15:10 svn2cl 使った。まずまず使える。
17:26 喉のイガイガがおさまったけれど、プロポリスのど飴のせいなのかベンザブロックLのせいなのか、はたまた自然治癒なのか不明。
19:05 また reStructuredText 使いたくなってきた。
19:18 セブン-イレブン限定 ZAKU II。 http://movapic.com/...
19:29 隣の人が日本酒臭い。酒臭いじゃなくて日本酒臭い。 [mb]
21:11 @maru_kei 確かに体臭+香水はきついよね。 [mb]
21:48 @maru_kei あ、今読みました。オメデトウ!
23:58 なんとか日付が変わる前に布団に入った。 [mb]

[ permalink ]

[ 11月9日全て ]

2010年8月18日 (水)

Windows に reStructuredText 環境を

ちょっとした仕様のドキュメトを書くのに、久しぶりに reStructuredText を使いたくなったので、Windows XP BOX に環境を用意した。

まず Python をインストール。公式サイトから python-3.1.2.msi をダウンロードしてインストール。インストール先は c:\usr\local\Python31 に。

次に reStructuredText 形式ファイルを HTML 形式ファイルなどに変換するツールが含まれている Doctils wを公式サイトから取ってくる。docutils-0.7.tar.gz をダウンロード。アーカイブを展開したら setup.py のあるディレクトリで

 c:\usr\local\Python31\python.exe setup.py install

を実行。これでインストール完了。これ例えば reStructuredText 形式で書いてある mydoc.txt ファイルを HTML 形式ファイル mydoc.html に変換するには

 c:\usr\local\Python31\python.exe c:\usr\local\Python31\Scripts\rst2html.py mydoc.txt mydoc.html

で OK。必要なら docutils.conf ファイルを作って --config オプションで渡してあげる。環境にあわせて rst2html.bat を作っておけば、Windows でもまずまず reStructuredText を使えるはず。

[ permalink ]

今日のさえずり: すごいね! サイコキネシスじゃん!

2010年08月18日

09:32 車内母子「すごいね! サイコキネシスじゃん!」(母)
09:33 RT @xnomb: 一松信先生（数学者）の本はわかりやすいなあ。
09:39 一松信先生懐かしいな。キャンパスで立ち止まっているときは、何かの計算をしているんだろうと言われてた気が。
12:06 おにぎり 315円。 (@ セブン-イレブン神田佐久間町店) http://4sq.com/cEfW1k
12:42 ほぼ日手帳2011のカバー、公式サイトでチラ見させている写真は女性向けっぽいのばかりだな。
12:46 もう横綱にしちゃっていいよ。 RT @as_tone: そして今日も「ここ横綱って地名があるんだ！」と言っている人がいる@両国。横網（よこあみ）です…
13:40 缶コーヒー 100円。
14:14 久しぶりに C++ から C# の世界へ。ヘッダファイル書かなくていいの楽だわー。
16:41 RT @rtmjp: 日本語によるRemember The Milkのtwitterアカウントを開設いたしました。最新情報、ブログ投稿、質問の回答などを行います。よろしくお願いします。参考までですが、ブログにも投稿しています。 http://ow.ly/2r9mX
18:15 久しぶりに reStructuredText 使いたくなって Windows XP BOX に Python 3.1.2 と Docutils 0.7 をインストール。
18:37 reStructuredText でちょっこし書いて rst2html して Google ドキュメントにアップロードしたら、変換できんってはねられた。
20:03 雨降ってきてる。 (@ 秋葉原駅 (Akihabara Station) w/ 12 others) http://4sq.com/68fhHr
20:26 こっちは今降ってない。
21:08 頂き物のゆべし食べた。名前はどこかで聞いたような聞かないような感じだったけど、食べてみたところ多分お初。昔風だな。
21:11 RT @America_Amazon: 友人の家に遊びに行ったらビニール袋に詰められた土が何個も飾ってあって、「何だよ、あれ？」と聞いたら「今まで付き合った女の家の、庭の土を記念に持って帰ってきたんだよ」という高校球児みたいな答えが返ってきた。リア充でも屈折するとキケンな ...
21:23 明日から花輪ばやしだね。
22:02 ぽ、PORTER ほぼ日手帳カバーだと!
22:03 @_kojihiro 岩手のお土産らしいです。
22:06 「手前のポケットはスマートフォンが収まるサイズ。」とか絶対狙い撃ちされてる。 RT @Naney: ぽ、PORTER ほぼ日手帳カバーだと!

[ permalink ]

[ 8月18日全て ]

2010年10月6日 (水)

今日のさえずり: レンズ付きフィルム握ってる若者見つけてホッコリした

2010年10月06日

09:23 今日も電車冷房入ってる。
09:30 1週間限定のウチカフェ「苺のロールケーキ」が大変気になる。
09:46 久しぶりにレンズ付きフィルム握ってる若者見つけてホッコリした。
12:08 弁当 350円。
14:13 コードリーテディングした内容のまとめを Word 使って書いているけど、やっぱ使い慣れないなあ。LaTeX2e? _ とか面倒だな。reStructuredText にするか。まあこちらは今度は画像の管理が面倒なんだけど。
14:37 やっぱり reStructuredText にした。圧倒的に速く書ける。
16:21 Samba で外部へのシンボリックリンクが辿れなくなっていた。Samba アップデートしたからか。[global] unix extensions = No にして、必要なセクションに wide links = Yes を追加。
17:23 コーヒー飲料 100円。
19:17 工数見積もり中。バッファとデバッグを10%ずつ盛ると結構な時間数になっちゃった。
19:34 ああ、そうだ国際化も考慮しないといけないんだっけ。
20:12 RT @zerobase: 成果物ベースで見積を出して一括請負する能力がなくて、人月見積で客先常駐で顧客の朝令暮改につきあい続けて現場が疲弊してるSIerって、いくつかの点に注目すればわりとアジャイルに近いところにいる。経営者が賢ければ変えられるんじゃないかな。
22:41 YAPC::Asia Tokyo 2010 会場の東京工業大学「70周年記念講堂」「百年記念館フェライト記念会議室」「東工大蔵前会館ロイアルブルーホール」って電源取れるとこないのかな? #yapcasia
24:11 Xperia の電池パックもう1個買い足すか迷ってる。手持ちの2個と合わせて3個必要なシチュエーションって滅多にないからなあ。

[ permalink ]

[ 10月6日全て ]

2010年11月11日 (木)

Evernote 上で reStructuredText で書いてクリップボード経由で HTML に

Evernote の書式機能はしょぼい。 Evernote 上でちょっとした文書を書く場合は reStructuredText 形式で書いておいて必要な時に HTML 形式などに変換したいのだが、ノートの内容に対してコマンドを実行する機能などがないのでクリップボード経由で rst2html を呼ぶようにしてみた。

Evernote for Windows 4 のノート上で全文選択して[コピー]後、以下の Perl スクリプトを実行するとクリップボードの内容に対して rst2html を実行して HTML ファイル生成後、デフォルトブラウザで開いてくれる。

 #!/usr/bin/perl
 
 use warnings;
 use strict;

 use Encode;
 use Win32::Clipboard;
 use File::Temp;

 my $clip = Win32::Clipboard();
 exit 0 unless $clip->IsText();
 my $text = $clip->GetAs(CF_UNICODETEXT);
 $text = Encode::decode("UTF16-LE", $text);
 $text =~ s/\015\012\015\012/\015\012/g;
 $text =~ s/\x{00a0}/ /g;                  # U+0020

 my $tmp_file = File::Temp->new(SUFFIX => '.rst');
 binmode($tmp_file, ":encoding(utf8)");
 print $tmp_file $text;
 system "rst2html", $tmp_file, $tmp_file . '.html';
 system "start", $tmp_file . '.html';

まずは的 Perl スクリプトなので、ファイルは一時ファイルとして作成していて削除もしていない。なお rst2html は設定ファイルで [general] input_encoding: utf-8 に設定してある。

Evernote のクリップボードテキストを処理するのに、ちょっと工夫がいる点は以下。