礼儀正しさ重要（Good Manners Matter 日本語訳）
以下の文章は、Rich Bowen による Good Manners Matter（Open Advice に収録）の日本語訳である。 Rich Bowen は、約15年もの間フリー／オープンソースソフトウェアに携わってきた。その時間の大半は Apache HTTP Server に費やしてきたが、Perl や PHP やいろんなウェブアプリケーションにも取り組んできた。彼は『Apache Cookbook』や『The Definitive Guide to Apache mod_rewrite』他いろんな本の著者であり、様々な技術カンファレンスに頻繁に参加している。 僕は2000年の9月に Apache HTTP Server のドキュメンテーションプロジェクトに携わり出した。少なくとも、僕が初めてドキュメントをコミットしたのはそのときだった。それ以前は電子メールでいくつかパッチを登録し
Pandoc - index
If you need to convert files from one markup format into another, pandoc is your swiss-army knife. Pandoc can convert between the following formats: (← = conversion from; → = conversion to; ↔︎ = conversion from and to) Lightweight markup formats ↔︎ Markdown (including CommonMark and GitHub-flavored Markdown) ↔︎ reStructuredText → AsciiDoc ↔︎ Emacs Org-Mode ↔︎ Emacs Muse ↔︎ Textile → Markua ← txt2t
GitHubに載せるHTMLファイルをコードから生成·Paige MOONGIFT
PaigeはコードやREADMEからGitHub向けの静的なHTMLファイルを生成するソフトウェアです。 インストールは簡単で「npm install paige」のみです。実行は「paige path/to/config」になります。 実際にPaigeを使って作られたインデックスページです。 元になっているのはREADMEファイルです。Markdown記述のファイル（恐らくそれ以外も可）からHTMLを生成しています。 ソースファイルごとに説明ページが生成されます。左に説明、右にソースコードが表示されます。結構見やすいです。 元になったコードです。コメントがそのままテキストとして説明文に使われている形になります。 このような設定を記述する必要があります。 この手のジェネレータは色々ありますが、Paigeはかなりシンプルに使える印象です。GitHub向けと銘打たれている通り、GitHub向け
論理的なプログラムを書くプログラマは、論理的な文章も書けるか？
論理的なプログラムを書くプログラマは、論理的な文章も書けるか？：誰にでも分かるSEのための文章術（10）（1/2 ページ） 「提案書」や「要件定義書」は書くのが難しい。読む人がITの専門家ではないからだ。専門用語を使わず、高度な内容を的確に伝えるにはどうすればいいか。「提案書」「要件定義書」の書き方を通じて、「誰にでも伝わる」文章術を伝授する。 連載の第5回「ドキュメントの質を確実に上げる6つの文章作法」、第6回「読みやすい文章の極意は『修飾語』にあり」では、分かりやすい文章を記述するためのポイントを説明しました。 読み手に理解してもらえる文章表現にするためには、1つひとつの文章を分かりやすく記述するだけでなく、文章の流れ（文章のつながり）が読み手にとって分かりやすいものでなければなりません。そこで今回は、「分かりやすい文章の流れ」を構成するポイントを解説します。 論理思考に慣れている技術
ドキュメンテーションを加速するストレスフリーの作図ツール『blockdiag』 jus2011年6月勉強会
システム開発や保守、運用の現場においてドキュメントは必須のものです。 しかし、ドキュメントの作成・維持には多くのパワーがかかるため、ドキュ メントが存在しない、資料が古いままになっているなどといった現状を多く 耳にします。 本勉強会ではこれらのドキュメントでよく利用される「図」にフォーカスし、 みるみるうちに図を作成できる「blockdiag」をご紹介します。 「blockdiag」はシンプルなテキスト記述からブロック図、ネットワーク図などの 画像ファイルを出力可能なオープンソースの画像生成ツールです。書き やすさ、メンテナンスしやすさを中心にデザインされており、図を作るのに 配置や並べ替えに苦労する必要はありません。 blockdiagのサンプルはこちら このような特徴を持つ「blockdiag」と、シンプルな記述でドキュメントを作成 するツール「Sphinx」を組み合わせることによって
The Most Important Code Isn't Code
Documentation is the single most important change I’ve made to my coding style in the last year. Documentation is Personal I’m not talking about injecting a few comments in front of confusing lines here and there. I’m talking about taking a firm, consistent view at how you document your methods, your classes, and your projects, and then sticking to that mentality. Documentation is mostly described
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
処理を実行中です
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
