質の高い技術文書を書く方法 - As a Futurist...
大学や大学院で論文の書き方を鍛え上げた人たちには遠く遠く及ばないが、僕の様なはぐれもの1でも最近は Amazon 社内で文書の質が高いと評価してもらえるまでにはなった。Software Engineer として、コードでのアウトプットはもちろん大事だけど、文書のアウトプット(およびそれによって得られた実際のアウトプット)は同じだけ重要である2。今回は自分が最近どういうところに気をつけて技術文書を書いているのか、ということについて数年後の自分が忘れてないことを確かめられる様にまとめておく。 そもそも文書とは？ 英語だと document。ここで指す(技術)文書とは、人間が読む文体で書かれた技術に関連する情報、といったものだ。具体的に言うと以下の様なものを想定している: 新しいプロジェクトの骨子を説明する資料 会議の叩き台となる 1 枚ペラ 本番環境に変更を加えるにあたっての包括的な情報や具体
Inclusive Technology Consulting - Bocoup
Building a back-end API layer introduces a whole new layer of coordination between server and client code. While there are many aspects to this delicate dance of communication, one key ingredient to minimizing back-and-forth-confusion-about what-call-does-what, is consistently communicating about your API endpoints. This is by no means rocket science, but over time I’ve created a template that I n
RDocとYARDの比較 - 2011-05-11 - ククログ
リファレンスマニュアルの記述方法を検討し、埋め込み方式のドキュメントツールを採用したとします。Rubyで埋め込み方式のドキュメントツールを使うとしたらRDocかYARDになります1。 RDocからYARDへの移行方法につなげたいのでYARDを使う方向で話を進めたいわけですが、その前にRDocとYARDの背景や機能の違いを確認しておきましょう。 RDocの背景 RDocはRuby 1.8.1からRuby本体に標準添付されています。Ruby1.8.1は2003年のクリスマスにリリースされているので、もう7年くらい前になります。Ruby本体や標準添付されているライブラリもRDoc用にドキュメントが書かれていますし、Rubyで標準的なドキュメントツールといえばRDocという存在です。 RDocは2004年くらいまではRuby本体のリポジトリ上で活発に開発されていましたが、それから数年は開発が停滞し
リファレンスマニュアルの記述方法 - 2011-05-05 - ククログ
Rubyではライブラリのリファレンスマニュアル作成のドキュメントツールとしてRDocが標準となっています。これは、古くからあるという理由とRuby本体に標準添付されているという理由からです。しかし、RDocはそれほど活発に開発されていないため、最近のドキュメントツールとして機能不足と言わざるをえません1。どのような機能が足りないのかについては別の機会にします。 数年前からYARD（Yey! A Ruby Documentation Tool）というドキュメントツールが開発されています。YARDはRDocとの互換性を残したまま機能を拡張しているため、RDocからの移行も容易です。実は、YARDは第2回フクオカRuby大賞（SSLの証明書の期限が切れているので警告がでます）に「Improving Documentation in the Ruby Community」というタイトルで応募してい
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
処理を実行中です
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
