エンジニア歴20数年の私が、設計書を書く際に心がけていること - Qiita

Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? はじめに 時の経つのは早いもので、私がIT業界に身を置いて四半世紀になってしまいました。 その間、膨大な数の「設計書（仕様書）」を書いて来ましたが、未だに悩み・迷いは尽きません。 それでも、亀の甲より年の劫とも申しますので、私なりの経験則を「個人」と「チーム」の両観点でまとめてみました。 本稿のテーマは、「主に設計書を想定した、開発ドキュメントの書き方」です。 本稿で前提とする設計書は、ExcelやWordで書かれた、フォーマルな（≒納品物になりえる）設計文書、です。 したがって、自社サービス開発よりも受託開発、アジャイルよりもウォータ

[ksugimori]

"用語を統一する" "造語をしない" これホント大事。経験的には大規模システムのバグは些細な認識のズレが原因であることがほとんど

[sifue]

正直1ページのREADMEで済むプロダクトなら良いけど、実際はwiki形式なりpdf形式なりで配布される設計書が必要な、多くの人が関わる規模のプロダクトもあるわけで、こういうTipsは素晴らしいと思います。

[hepoko_ks]

ドキュメンテーションのtipsとしてみればExcel仕様書だけでなくOSSのREADMEでも十分価値がある部分もあるんだけど。。。SIerの匂いがしたら条件反射で切り捨てるような人間にはなりたくない。

[jiro68]

良い記事。アジャイルだろうがWeb開発だろうが、そのシステムが停止するまで一切の記憶を失わずに面倒を見続ける覚悟が無いならドキュメントはちゃんと整備する事は必須。

[otihateten3510]

これを 「誰が・いつ・どのタイミングで」やるかと、どう時間を捻出するか知りたい。

[don_ikura]

用語集があると途中参画メンバも楽

[snicmakino]

構造的に分かりやすい文書の書き方のシンプルな指針を示してくれるとても良い記事。Excel仕様書アレルギーな人が多いので、ちょっと心配しながらおそるおそるコメント見たら優しい世界で安心した。

[cardboarder]

「文章書きの上達のためには、訓練しかありません。」「一番大事なのは、身近に厳しく添削してくれる方がいること」 | 書き慣れている（と思っている）人ほど見直すべきっぽい

[maname]

用語が統一されてないものをOKとしてしまうレビュアをどう教育したら良いか悩むことある

[GEROMAX]

これは相当に重要な事なんだけど、しっかりできる人はかなり希少。これができる人が自分以外にもう一人居ないと、ドキュメントの品質維持は難しい。

[nakkisan]

チームでマニュアルを作成する時などに、継続して意識しておくべき鉄則が書かれている

[badbadkofkof]

設計

[iww]

主語と用語の統一は超大事。 おろそかにすると、改変するときに死ぬ

[nacika_inscatolare]

]

[k-holy]

設計書というか文書の書き方だった。特に用語統一は業種職種関わらず全ての人が気を付けて欲しい。同じ用語が複数の意味で使われていたり、ユーザー側で不適切な用語が蔓延してると設計側としても非常につらい。

[rocketboy_miya]

用語の統一は退職まで言い続ける覚悟が必要

[an_emerald]

用語統一、変更履歴…わ か る ！！

[Wacky]

“文章書きの上達のためには、訓練しかありません。 一番大事なのは、身近に厳しく添削してくれる方がいること、だったりします。”

[raitu]

基本の基本の基本、故に超大事

[lalupin4]

'[glossary] とかタグを付けて、チケット発行しまくりです。

[tbpg]

用語集気になっている。ちゃんと管理している場所にいたことがない。ノウハウを知りたい "プロジェクト内で用語集を作りましょう"

[koji28]

あとで読むかも

[Nyoho]

いい心がけなのでしっかりブックマーク🔖

[privates]

造語は作らないには大賛成。ですが理解してくれない人（特に上司）に碎けて説明した造語を独り歩きさせられた事が沢山ある。標準な言葉で会話するのは大変だと、常々思っています。

[natu3kan]

わりと地方で有名なIT企業でも仕事のやり方とか用語の定義の統一化がされてなかったりするからなあ

[gfx]

心がけか…エモいやつかな…と思ってスルーしてたけどテクニック集だった。よい。

[golden_eggg]

意識的か無意識的かに関わらず、ほんの些細な認識のズレや用語の不統一が大きな不幸を招くの、特に外の会社さんとのやり取りが頻繁な案件ではアルアルなので、webだろうがSIerだろうが関係なく大事な知見だ

[sds-page]

ベンダーとユーザーで用語統一できてない案件は嫌われる覚悟で厳しく突っ込まないとあとでクラッシュしたときに大事故になる

[mather314]

開発しやすいかどうかというよりプロジェクト全体で共通認識が作れるかどうかだよね…。この辺は設計だけじゃなくてプロジェクト全体で意識を合わせないと不可能な気がする…。

[luccafort]

書いてる内容に大きな間違いはないと思うんだけどコメントで絶賛されているのに違和感がある。表記ゆれとか問題もわからなくはないけど本質はそこではないのでは？というこれで開発しやすくなるのか？と疑問。

[maruyamatk]

氷河期世代がすっぽりといないため、こういう知見が失われている現場が多い。

[mabushii_sign]

良い記事。普段なんとなく感じてることがキレイにまとまっている。

[hiroyuki1983]

既存のドキュメントの仕様に合わせるかな。というかドキュメント標準化レビューとかないの？

[gokichan]

すごく当然のことなんだが。これだけブクマをあつめるということは、新人教育とかで教えていない会社が多いんだろうな。

[gin0606]

設計書だけじゃなくてドキュメントとか文章の書き方みたいな感じだった

[adwhing]

すごくいい。デスクに貼っておきたい

[itouhiro]

「ほとんどは図と表にできる。箇条書き、一文を短く。用語を統一。用語集作る。造語しない（日付関連）。変更履歴の残し方を決める。主語を統一。まず全体像 → 詳細。章立てだけ作り添削を受ける」

[sigwyg]

ごく普通のことだと思ってたけど、なんかべた褒めされてて、けっこう感覚でやってる人多いんだなーって文系的発想。

[mongrelP]

エンジニアじゃなくても普通に有用な話だ…

[ksakae1216]

なるほど～。　ちなみにこの記事も読みやすい！！