満足せる豚。眠たげなポチ。:業務システム開発でドキュメントを作ることについて
職場でここ３〜４ヶ月の間、システム再構成のためのドキュメント化プロジェクトというのを進めてきた。その中で『ドキュメントを書く』ということに対する意識が随分自分の中で変化したので、メモしておく。 まずは経緯から。 そのシステムは、いわゆるレガシーなシステムで、十数年来の歴史を持つ。これまで基盤が多少変わることがあっても基本的にソフトウェアアーキテクチャ（どのような単位で機能をモジュール化するか、どのように機能を抽象化し変化に対して柔軟にするか）に変わりはなく、作った当初の設計にツギハギしてメンテナンスを続けていた。 元々は、一体何をすれば増員以外の手段で開発量を上げられるかということを議論していた。現行のアーキテクチャのままでは求められる開発期間とバージョンアップのサイクルに対して近い将来限界を迎えることが明白であったためだ。 今のアーキテクチャや設計に問題があり、メンテナンス性を大いに損ね
HowToWriteAnEffectiveDesignDocument - 設計文書のうまい書き方
HowToWriteAnEffectiveDesignDocument - 設計文書のうまい書き方 目次 この文書について 設計文書のうまい書き方 なぜ設計文書を書くのか 良い設計とは何か 同僚の開発者に向けて書く 第 1 節に書くこと: プロジェクト/サブシステムの目的を示す 第 2 節に書くこと: 設計に使う高レベルなエンティティを定義する 第 3 節に書くこと: 個々のエンティティに関する低レベルの設計を書く 使い方 設定 モデル 相互作用 第 4 節に書くこと: 利点, 前提, リスク/懸念事項 マネージャ向けに書くこと 最後に 設計文書のうまい書き方 この文書について "How to Write an Effective Design Document" の日本語訳です. http://blog.slickedit.com/?p=43 推敲歓迎: 誤訳, タイポ, 訳語の不統一,
steps to phantasien t(2007-07-06)
昔の同僚が退社してベンチャー仕事をやるという. 門出を祝う宴会に, 昔のよしみで呼んでもらった. ついでに古巣の近況を聞く. ひとつ嬉しい知らせがあった. 以下その自慢話. ある夏, 私は社内ライブラリのチュートリアルを書いた. そのチュートリアルが, 今でも改訂されながら参照されているという. のみならず新人プログラマの研修教材として広くとりいれられつつあるそうだ. 私はとても嬉しくなった. もちろん手柄は改訂を続け, 様々な改善を続けた彼らのものだ. それでもなお私は喜びを隠せない. 自分が去った今も文章だけが生き続けている. 私は平凡なプログラマだから, 自分のコードが生き残れるとは思えない. 一方ボランティアで仕事の合間に書いた文章は読み継がれている. 価値のあるものが生き残るのなら, 私のなした価値は(コードではなく)文書にあったことにある. プログラマとしては悲しいけれど, 会
@IT:ITエンジニアにも必要な国語力 第12回 個条書きを過信してはいけない
コミュニケーションスキルの土台となる図解言語。だが筆者によると、実はその裏に隠れた読解力、国語力こそがITエンジニアにとって重要なのだという。ITエンジニアに必須の国語力とはどのようなものだろうか。それを身に付けるにはどうしたらいいのか。毎回、ITエンジニアに身近な例を挙げて解説する。 ■個条書きは相互の関連を表さない 連載第9回「メタ情報とサマリーで『伝わる』ビジネス文」、第10回「複雑な条件を文章で書くべからず」、第11回「階層と名前の不一致に注意する」にわたって、「こんな説明では分からない」10種類の失敗パターンを以下のように列挙した。 （1）メタ情報の欠落 （2）要点の分からない見出し （3）複雑な条件の文章表現 （4）分類を表さない名前 （5）過剰な言い換え （6）対称性のない表現 （7）指示代名詞の多用 （8）相互関連の分からない個条書き （9）時系列の乱れ （10）語感と実感
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
処理を実行中です
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
