ドキュメント作成に役立つ「日本語スタイルガイド」の紹介：CodeZine
はじめに 大量のドキュメントの執筆作業を複数のメンバーで行うとき、各メンバーの文章表現にどうしても差が出ます。特に、直接ユーザーの目にとまるマニュアルなどは、用語、表現を統一することがとても重要です。 大量の翻訳マニュアルを作成するSun、Microsoftでは、翻訳作業の指針とする『日本語スタイルガイド』を公開しています。本稿では、それぞれの『日本語スタイルガイド』関連情報を紹介します（ガイドラインの内容はそれぞれをダウンロードしてご覧ください）。Sunの日本語翻訳ガイドライン Sunの翻訳ガイドラインについてまとめたページがあります。Sunの日本語翻訳ガイドライン スタイルガイドをダウンロードできます。スタイルガイドのダウンロード（PDF形式） スタイルガイドは100ページにおよびますが、4ページにまとめたクイックリファレンスを、翻訳プロジェクトのReiko Saitoさんのブログ
MOONGIFT: � Wikiのように開発者向けドキュメントを共有する「DocBox」:オープンソースを毎日紹介
プログラマのためのドキュメントと言えば、JavaDocやRDoc、PHPDocなどが有名だ。これらはソース上にコメントとして書けるので、実際のコーディングとドキュメントとが乖離するのを防ぐことができる。 RDocを閲覧できる だがそれらのドキュメントをいちいち生成していたのでは面倒だ。編集の手間も軽減するこれを使ってみよう。 今回紹介するオープンソース・ソフトウェアはDocBox、RDocコラボレーションソフトウェアだ。 DocBoxはRDocをまるでWikiのように扱うことができるソフトウェアだ。ソースコードをDocBoxにインポートして動作する。ドキュメントはWikiのようにWebベースで編集が可能だ。 Web上で編集できる 編集した内容は元のソースコードへの反映したり、Gitリポジトリのドキュメントブランチへのコミットができるとのこと。*.rbファイルや、READMEファイルが対象に
ドキュメントとして何を書くか？
僕の考えは、以下のような感じ。 (1) ドキュメント（設計書だろうが仕様書だろうが）は、「誰に何をどう伝えるべきか」を考えれば、何を揃えればいいかは自然と決まってくる。そして、誰が読んでも意味がないと判断されるドキュメントは意味がないので書かない。 (2) 「基本設計書」や「詳細設計書」や「外部設計書」や「内部設計書」という言葉があるが、肝心なのは「誰に何を伝えるか」であり、伝えたいことや認識あわせの単位でドキュメントが作られればそれでいい。それらをまとめて「○○設計書」とするかどうかは、顧客がそうしたければ好きにすれば良い（そこまでやる義務は開発側にはないと思う）。 (3) アーキテクトの仕事は、各作業者が何をしたらいいか迷うことなく作業ができるように「決めごとをしていくこと」。その決めごとは、すべてドキュメント化されるべきであり、そのためには「誰に何をどう伝えるべきか」を考えていけば、
満足せる豚。眠たげなポチ。:業務システム開発でドキュメントを作ることについて
職場でここ３〜４ヶ月の間、システム再構成のためのドキュメント化プロジェクトというのを進めてきた。その中で『ドキュメントを書く』ということに対する意識が随分自分の中で変化したので、メモしておく。 まずは経緯から。 そのシステムは、いわゆるレガシーなシステムで、十数年来の歴史を持つ。これまで基盤が多少変わることがあっても基本的にソフトウェアアーキテクチャ（どのような単位で機能をモジュール化するか、どのように機能を抽象化し変化に対して柔軟にするか）に変わりはなく、作った当初の設計にツギハギしてメンテナンスを続けていた。 元々は、一体何をすれば増員以外の手段で開発量を上げられるかということを議論していた。現行のアーキテクチャのままでは求められる開発期間とバージョンアップのサイクルに対して近い将来限界を迎えることが明白であったためだ。 今のアーキテクチャや設計に問題があり、メンテナンス性を大いに損ね
窓の杜 - 【NEWS】各種文書をFlashドキュメントへ変換できる「Print2Flash Free Edition」
各種文書ファイルをWeb上で公開・共有したいときに便利な仮想プリンター「Print2Flash Free Edition」v2.7.1が、2月13日に公開された。Windows 2000/XP/Srever 2003/Vistaに対応するフリーソフトで、利用は個人かつ非商用目的に限られる。現在、作者のホームページからダウンロードできる。 近年、Web上で文書を公開するときにはPDFファイルが利用されることが多く、「Adobe Reader」をパソコンにインストールしていれば、Web上のPDFファイルをWebブラウザー内に表示できる。しかし厳密に言うと、PDFファイルはWebコンテンツ用の規格ではないため、「Adobe Reader」がWebブラウザーに代わってPDFファイルを表示しているにすぎない。 一方、Web上で公開されている動画の世界に目を向けてみると、“YouTube”などではFl
各種ドキュメントをFlash化·Print2Flash Free Edition MOONGIFT
ちょっと前までは文書をPDF化するのが便利だった。プリンタドライバとして動作するPDF作成ツールも数多く登場している。PDFを作成するのは決して難しいものではなくなっている。 次の段階はドキュメントのFlash化だ。この利点は何だろう、閲覧は当然としてブラウザ内で見られるのが便利な点だ。 今回紹介するフリーウェアはPrint2Flash Free Edition、プリンタドライバとして動作するFlash生成ソフトウェアだ。 実はPrint2Flash自体はフリー版ではないものを持っている。Memotuneの中で一時的に利用していた。FlashPaper同様にFlashであればOSの垣根を越えて、さらにブラウザ内でインライン表示できるのが便利だ。 Print2Flash Free Editionはそのフリー版であり、個人の非商用に限って無料で利用できる。利用方法は簡単で、プリンタのように印刷
[Think IT] 第1回：開発ドキュメントって何ドキュか？ (1/3)
【楽々デブドックを書こう！】開発☆ドキュン 第1回：開発ドキュメントって何ドキュか？ 著者：シンクイット編集部 公開日：2008/02/01（金） 妖精さんと学ぶ開発ドキュメント システム開発も終盤に差し掛かってくると、疲れが溜まったり、睡眠時間が足りないといったために「ふっ」と意識が遠のくことがある。しかし、自分で入力した覚えがないのにコードが書かれていたり、知らないうちにバグがどこかに消えていた、ということはないだろうか。 実は開発者の作業能力が低下すると、C言語で開発しているのなら「C言語の妖精さん」、Java言語で開発しているなら「Java言語の妖精さん」が、どこからともなく現れて、あなたの代わりに作業を続けてくれているのだ。 古くから使われている言語であれば、妖精さんたちも高いスキルを誇っているのだが、最近になって登場したり、重要視されるようになった箇所の妖精さんは、まだまだ新人
満足せる豚。眠たげなポチ。:ドキュメントは重要ではない。なんて言わない。
「（相対的に）ドキュメントは重要ではない。」と考えていたけど、改宗する。「そのドキュメントが何を表現するかを考えずに、ドキュメントを作る」という行為が無駄なのであって、「設計を文書にして残す。それをレビューする。」という行為はけして無駄じゃない。やるべきなのは、「何をドキュメントにするか、何をドキュメントにしないかを判断すること」と、「レビューして、設計での一定レベルの合意を形成すること」だ。そして、その目的は「品質の高いインターフェースを持ったコードを共有し、スケールさせることができるようにする。」という点に尽きる。 ふつうのプログラマで成り立つプロジェクトだからこそ、上記を徹底しないといけない。詳細設計として程度の悪い擬似コードを日本語で書いたようなドキュメントを受け取る必要は当然なく、その分、たとえばビジネスルール単位で、それをどのように設計するのかを検討する必要がある。これをコード
MOONGIFT: » Markdown/HTML/LaTexを相互変換「Pandoc」:オープンソースを毎日紹介
プログラマはテキストフォーマットが一番大好きだ。かくいう私も好きだ。だが、ある程度形式ばった文書が必要な時もある。例えば仕様書などだ。 そうした時だけMS Wordをはじめとしたワードプロセッサを使う人もいるだろうが、とかく面倒くさい。テキストファイルからみられる形式に変換してくれるソフトウェアだ。 今回紹介するオープンソース・ソフトウェアはPandoc、各種フォーマットの相互変換ソフトウェアだ。 PandocはCUIベースのソフトウェアで、ある形式の文書を別な形式に変換できる。読み込める形式として、MarkDown、構造化されたテキスト、HTMLそしてLaTexが対応している。そして、出力形式としてこれらに加えてConTeXt、DocBook、RTF、manそしてs5プレゼン形式になっている。 例えば、テキストファイルを元にs5形式で出力してプレゼンテーション資料を作り、配布はLaTeX
Java Documentation in Windows Help format (WinHelp and HTMLHelp)
This Web site provides various Java documentation converted to Windows Help format. WinHelp and HtmlHelp systems provides a structured table of contents, a complete index, and a full-text search feature. Don't remember the parameters of StringBuffer.replace() ? Just type 'replace' in the index, and you get it in a snap. Alternatively, you can browse the table of contents tree to find the StringBuf
DocBookによるドキュメント作成：CodeZine
はじめに DocBookはテクニカルドキュメントをXMLで作成するためのOASIS標準で、SpringやHibernateのドキュメントはDocBookで生成されています。DocBookは特にコンピュータ関連のコンテンツに適しており、テクニカルコンテンツ用のDTD（Document Type Definition）とXMLスキーマによって定義された一連のXMLタグで構成されています。DocBookおよびその他のオープンソースプロジェクトには、DTDの他にも、DocBook対応のXMLをPDF、HTML、Eclipse Help、およびMANページに変換できるようにするツールとフレームワークのコレクションが用意されています。これにより、同じマテリアルを何度も記述したり、手動で形式を変換したりする手間を多少緩和することができます。 「そんな大騒ぎするほどのことでもないね。必要ならHTMLでもE
「市場の要求を満たせない」：ODF陣営の主要人物ら、Compound Document Formatsに転向
非常に優れた1つの文書規格というものは、決して存在しないようである。 文書フォーマットをめぐる大きな論争に新たな展開が生じた。「OpenDocument Format（ODF）」推進派の一部が、同規格からWorld Wide Web Consortium（WC3）の「Compound Document Formats（CDF）」規格へと転向し始めたのである。 理由は、ODFファイルを「Microsoft Office」アプリケーションと共有する際に、技術的な制約が存在するからである。 OpenDocument Foundationを設立したGary Edwards氏は2006年、「OpenDocumentでは市場の要求を満たすことができない」と述べた。「そもそもOpenDocumentは、市場の要求を満たせるような設計になっていないのだ」（Edwards氏） Edwards氏は同僚らととも
ここギコ！: Visual Source Safe+Google Desktop Searchでもドキュメント管理
2005年06月01日 Visual Source Safe+Google Desktop Searchでもドキュメント管理 こちらで報告したSubversion＋GDSでドキュメント管理をするシステムの案ですが、社内レビューをしたところ、やはりWordやExcelといったバイナリファイルをバージョン管理するのに、SubversionやCVSといった衝突検知->マージ型のバージョン管理は難しいのでは、という検討結果になった。 Diffが効かないので、下手をすれば差分を抽出するのにかかる時間・手間のコストの方が、バージョン管理で得られるメリットに勝る場合があり得るからだ。 やはりバイナリドキュメントを管理するのならば、完全排他型の管理でなければ、という話になった。 一理ある。 で、またいろいろ大勢で検討していると代案も出てくるもんで、完全排他型のバージョン管理システムの代表であるVSS
MOONGIFT: � Javaベースのドキュメント管理「O3Spaces」:オープンソースを毎日紹介
Memotuneも含め、ドキュメントを管理するサービスが続々と登場してきている。ドキュメントをどこからでも手軽に見られるというのは便利だ。 オフィスの基本ともなるドキュメント、それを管理するインタフェースとして、こんなものも登場している。 今回紹介するフリーウェアはO3Spaces、OpenOffice/StarOfficeに対応したドキュメント管理サーバだ。尚、フリーなのはコミュニティ版で、10ユーザまでとなっている。 O3SpacesはJavaベースのソフトウェアで、Windowsであればインストールするだけでサービスが起動する。利用はWebブラウザベースになる。他にRPM、Debianパッケージ、VMWare版が用意されている。 ドキュメントのアップロードやそれをリスト化できる。実際の編集はローカルで行う。そして同じファイルをアップロードするとリビジョン管理される。ドキュメントはコメ
アーキテクチャドキュメントに必要なこと [arch]
最近本腰を入れて大掛かりなアーキテクチャ設計をしようとしているが，ドキュメントを書く際にいつも帰ってくるのがこのエントリー． Hitchhiker's Guide to Software Architecture and Everything Else - by Michael Stal: What should be in an Architecture Document? とても素晴らしい内容なので，以下に意訳しておきます．ぜひ原文も合わせて読んでみて下さい． - ドメインモデル (もしあれば)，使用されているパターン，ガイドラインなどに特化したドキュメントを合わせて紹介すること．アーキテクチャドキュメントは，それらのガイドラインと整合性を保つこと． - 1つのドキュメントは50ページを超えないこと．肥大化したドキュメントは誰にも読まれない (少なくともその全ての内容は)． - 当たり
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
こんにちのナリッジワーカーにとって、UIパラダイムはドキュメント指向よりストリーム指向がよいか?
TechCrunch | Startup and Technology News
TechCrunch | Startup and Technology News
Java Documentation in a Windows HTMLHelp (CHM) file – Kyle Cordes
Searchable Rails API Docs?