どうして開発者がドキュメントを書くべきか - 2011-10-27 - ククログ
オフィス文書形式が要求されるようなドキュメントではなくて、自分が開発したライブラリのドキュメント（リファレンスマニュアルやチュートリアルなどライブラリのユーザーが読むためのドキュメント）の話です。以下の「ドキュメント」もそのような意味で使っています。 使いやすいライブラリを開発したかったらプログラムだけではなくドキュメントも書くべきです。 なぜドキュメントを書くか ドキュメントを書く習慣があるかどうかは開発者によってあったりなかったりです。使っているプログラミング言語に相関がある気もしますし、リリースするかどうかに相関がある気もします。理由はいろいろあるでしょうが、ドキュメントを書く習慣のない開発者の方が多いでしょう。 書かない理由はこんな感じでしょうか。 面倒。 自分しか使わないからいらない。 どのように書けばよいかわからない。（どのツールを使えばよいかわからない。） 一方、書く理由はこ
Sphinxの国際化機能を使って複数言語用ドキュメントを用意する方法（概要） - 2011-05-31 - ククログ
YARDのことの続きを書きたいと思いつつもなかなか辿りつきません。今回はPython製のドキュメントツールSphinxの話です。groongaのケースを例にしてSphinxで複数言語用のドキュメントを生成する方法の概要を紹介します。書いていたら長くなったので、具体的にどうするかというのは次の機会にします。 5/29にgroonga 1.2.2がリリースされました。今後は日本だけではなく世界でも使ってもらえるように、英語でも情報を発信していく方向になりました。そこで、今回のリリースに合わせてサイトデザインをリニューアルし、英語のページも用意しました。ただし、すでにあった日本語のコンテンツを今回のリリースで全部英語にした、というものではありません。今回のリリースでやったのは「日本語と英語という複数の言語で情報を発信する仕組み」を作るところまでです。せっかくなので、今回のリリースで導入した、Sp
プログラミング言語のドキュメント検索をもっとリッチに - 2011-01-26 - ククログ
昔から「Rubyはドキュメントが弱い」と言われてきました。「PythonやPHPはあんなにドキュメントが揃っているのに、それに比べてRubyは。。。」というわけです。でも、待ってください。ドキュメントは記述が充実しているだけで十分ですか？簡単に目的のドキュメントにたどりつけますか？ GoogleやBingなどの検索エンジンや、Amazonを筆頭とするECサイトは「探しものを見つけやすくする」ことにどんどん磨きをかけています。なぜ、ドキュメントの検索機能はそれほど進歩しないのでしょうか？ ドキュメントの検索機能が、検索エンジンやECサイトでも使われているような最新の検索パターンを取り入れ、もっとリッチになればプログラミングがもっと楽しくなるはずです。それをRubyのドキュメントで実現しようとしているのがるりまサーチです。 最近、るりまサーチがよりパワーアップしたので、どう変わったかを紹介しま
Shibu's Diary: 日本語でSphinxを使う時のストレスを減らす拡張機能
渋日記@shibu.jp 渋川よしきの日記です。ソフトウェア開発とか、ライフハックを中心に記事を書いていきます。 Taken by mismisimos under CC BY-NC-SA Sphinxで日本語を書くときに、日本語の途中で改行を入れると、そこに空欄の文字が入ってしまい、ブラウザで見るときにちょっと見た目が悪くなったりします。まぁ、これはSphinxのせいというよりも、ブラウザのせいですが。 あと、Sphinxというか、docutilsは欧米の言語を対象としている仕様のため、太字にしたり、インラインマークアップを使うときには前後にスペースが必要となります。レンダリング後もこのスペースが残ってしまうため、ブラウザで見るとやはり改行と同じ悪さをします。バックスラッシュというか円記号でエスケープしたスペースを挟めばなんとかなりますが、面倒ですよね？ ということで、軽く作ってみたSp
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
処理を実行中です
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
