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

はじめに 時の経つのは早いもので、私がIT業界に身を置いて四半世紀になってしまいました。 その間、膨大な数の「設計書(仕様書)」を書いて来ましたが、未だに悩み・迷いは尽きません。 それでも、 亀の甲より年の劫 とも申しますので、私なりの経験則を「個人」と「チーム」の両観点でまとめてみました。 本稿で前提とする設計書は、ExcelやWordで書かれた、フォーマルな設計文書、です。 したがって、自社サ...

記事へジャンプ

みんなの反応

はてなブックマークでの反応
1otihateten3510@hatena 2018/02/14 14:41
これを 「誰が・いつ・どのタイミングで」やるかと、どう時間を捻出するか知りたい。
2programmablekinoko@hatena 2018/02/14 23:36
清く正しいエクセル設計書道
3perl-o-pal@hatena 2018/02/15 00:53
SIerのシステムで、実体とあってるドキュメントなんて見たことないしな。多分、みんなが思ってるほど必要ないと思う。
4masa_grant55@hatena 2018/02/15 01:12
手段の目的化(書くのは設計のためか、設計書の質を高めるためか)
5hepoko_ks@hatena 2018/02/15 01:23
ドキュメンテーションのtipsとしてみればExcel仕様書だけでなくOSSのREADMEでも十分価値がある部分もあるんだけど。。。SIerの匂いがしたら条件反射で切り捨てるような人間にはなりたくない。
6sifue@hatena 2018/02/15 01:35
正直1ページのREADMEで済むプロダクトなら良いけど、実際はwiki形式なりpdf形式なりで配布される設計書が必要な、多くの人が関わる規模のプロダクトもあるわけで、こういうTipsは素晴らしいと思います。
7endok@hatena 2018/02/15 02:01
メンテに工数取られるけど、SIer的には仕様変更の拠り所になるため必要かと。/設計書のバージョン付けルールを決め忘れて、いつのまにかメジャーバージョンがどんどん上がってしまった悲しい思い出ある。
8ksugimori@hatena 2018/02/15 02:09
"用語を統一する" "造語をしない" これホント大事。経験的には大規模システムのバグは些細な認識のズレが原因であることがほとんど
9mooonymann@hatena 2018/02/15 02:51
“Excelから脱却して、Markdownとかにして、バージョン管理システムに入れるのが良いのでしょうが…(政治的な要素もあったりして)なかなか難しい。”
10endor@hatena 2018/02/15 03:57
良い記事。
11nati_ueno@hatena 2018/02/15 04:41
良記事。定義のない造語が沢山ある資料を読むのは苦痛、、
12snicmakino@hatena 2018/02/15 05:23
構造的に分かりやすい文書の書き方のシンプルな指針を示してくれるとても良い記事。Excel仕様書アレルギーな人が多いので、ちょっと心配しながらおそるおそるコメント見たら優しい世界で安心した。
13chess-news@hatena 2018/02/15 07:10
技術文書
14asami829@hatena 2018/02/15 07:19
手順書にも使える。
15YukeSkywalker@hatena 2018/02/15 07:27
「フォーマルな設計文書」困惑/用語はほんま統一して欲しい(今の現場に向けて叫びたい言葉
16jiroron666@hatena 2018/02/15 07:29
設計書書いたことなかったので参考になります。
17unsoluble_sugar@hatena 2018/02/15 07:30
めも
18airj12@hatena 2018/02/15 07:37
目的(記載範囲)を定め、章立てを決めて、用語を統一し、インデントや箇条書きの記方を統一するとよくてそれがやりやすいのがWordなんだけど嫌う人が多くて…
19gonta616@hatena 2018/02/15 07:42
設計書というか、readmeやwikiを書くときにも気をつけること。そーいや、著名OSSとかreadmeわかりやすいけど、アレはどーゆースキルを構築してくんだw?
20kootaro@hatena 2018/02/15 07:46
いい知見です。
21sabacurry@hatena 2018/02/15 07:47
わかる。wordだとこの辺りはやりやすい。
22root48694062@hatena 2018/02/15 07:58
構成(章立て・文章)、表記揺れなど
23kenzy_n@hatena 2018/02/15 07:59
分かりやすく、誤りにくいを心掛ける。
24fufufukakaka@hatena 2018/02/15 08:05
設計書バージョン管理されろ(されてほしい)
25Harnoncourt@hatena 2018/02/15 08:06
「誰が・いつ・どのタイミングで」やるかと・・・ ←それに加えて合意と承認プロセスね。ここまでできて仕事です。設計書を書くのはただの作業です。これに気づかないとダメですよ~(白目)
26kei_0000@hatena 2018/02/15 08:07
目的を書く、文章は短め、図・表を使う、主語・用語を統一、変更履歴の残し方、等など
27seal2501@hatena 2018/02/15 08:13
今の現場、手順書が50本近くあるのに書く人によってフォーマットバラバラ。定義作って提案したら、そんなしっかりした作業にする必要ないからと却下されてやる気が失せてる🤔
28yamaisan@hatena 2018/02/15 08:13
参考にする
29pochi-mk@hatena 2018/02/15 08:15
良い。ここに書かれているルールについてlintというか自動チェックできればすごくすごくありがたいのだが…
30atori07@hatena 2018/02/15 08:22
たしかに。 気をつけます
31uturi@hatena 2018/02/15 08:25
“赤→青→緑→…と、変更が入るたびにカラフルにしていくメンバーがいたり” あるある。エクセルだとgit管理しづらいからカラフルになりがちなんだよな。
32piro77@hatena 2018/02/15 08:27
粒度が難しいよね(´・ω・`)
33suthio@hatena 2018/02/15 08:33
一つ一つがプラクティスになってる。 使えるものから少しずつ使うのが良さそう
34yosukegatz@hatena 2018/02/15 08:36
うん。基本ですね。新人くんは読むべき。
35notsunohito@hatena 2018/02/15 08:41
造語をしないのは大切
36Rinta@hatena 2018/02/15 08:44
金科玉条って感じでもないし、バランスの取れた、どこの現場でも概ね通じそうな内容。良いと思う。
37mangakoji@hatena 2018/02/15 08:47
インデント重要だけど、普段インデントしたコード的なモノ見慣れてないとちんぷんかんぷんなのかもと思ったり
38mugitora@hatena 2018/02/15 08:47
あとは冒頭に、文書の対象読者、記載範囲について明記すると書きやすく読みやすいと感じてる
39santos_testaly@hatena 2018/02/15 08:47
Excel仕様書って嫌でも書く機会多いし参考になる
40yuangao@hatena 2018/02/15 08:51
用語の統一と造語をしないのは大事よね。特に委託先など社外に出て行く設計書やRFPとかだと尚更のこと。
41cl-gaku@hatena 2018/02/15 08:53
"ExcelやWordで書かれた、フォーマルな設計文書"何で書かれてても通用するいい話だと思ったけど
42torimal3104@hatena 2018/02/15 08:56
うーん参考になる
43GEROMAX@hatena 2018/02/15 09:02
これは相当に重要な事なんだけど、しっかりできる人はかなり希少。これができる人が自分以外にもう一人居ないと、ドキュメントの品質維持は難しい。
44hanajibuu@hatena 2018/02/15 09:03
設計書のサンプルを是非公開して欲しい。
45sai0ias@hatena 2018/02/15 09:15
設計書に限らず各種ドキュメントで言える話だな。
46kuniku@hatena 2018/02/15 09:18
whatと同じレベルでwhyを残すことは心がけてる。人が変わっても、何年後か忘れても、保守やシステム変更で役立つ
47xlc@hatena 2018/02/15 09:19
オフショア開発を生業とする立場から言わせてもらうと、用語の統一は物凄く大切だが、仕様書を言葉に頼って書くこと自体を改める必要がある。ほとんどは図と表にできる。
48don_ikura@hatena 2018/02/15 09:21
用語集があると途中参画メンバも楽
49kouyan_h@hatena 2018/02/15 09:25
用語を統一するって事には本当に共感できる
50koogawa@hatena 2018/02/15 09:27
良い記事だった。変更履歴を残してくれない人も出てくるので、なんとか自動化したいところ
51bird_dip_jp@hatena 2018/02/15 09:31
まずは「日付」に99年99日とか入れるのは止めてもらおうか。
52tettekete37564@hatena 2018/02/15 09:34
ほぼ同じ。追加で、見出しはその節・項のサマリになるようにする。可能であれば節・項の1行目はの"見出し"を定義する文章に する。これをやっておくと 見出しのアウトラインから構成がおかしいところを見つけやすい
53fal-works@hatena 2018/02/15 09:41
用語集いいですね。あと抽象化レベルの意識かな、ここはなぜこういう設計か? とか、複数箇所に共通するルールがあるかとか。しかし期限が迫るとまっさきに犠牲になるのがドキュメント、それが一番の問題
54kmttr@hatena 2018/02/15 09:43
これは覚えておきたい。
55motch1cm@hatena 2018/02/15 09:44
良い
56bonz3@hatena 2018/02/15 09:46
「だれが・いつ?」ってブコメあるけど、ウォーターフォール前提とあるので「開発担当者が・コーディングの前に」てことになると思う。まともな案件なら設計書く時間もスケジュールに組まれる。
57cardboarder@hatena 2018/02/15 09:52
「文章書きの上達のためには、訓練しかありません。」「一番大事なのは、身近に厳しく添削してくれる方がいること」 | 書き慣れている(と思っている)人ほど見直すべきっぽい
58t1033@hatena 2018/02/15 10:02
アジャイルでも大規模開発なら書くで。目的は後からチームに入って来たときのナレッジ共有のため。まあエンジニアというよりPO向けにだけど
59utonn@hatena 2018/02/15 10:02
「本書では◯◯機能の仕様について記載する」これは目的ではない
60kaipu1224@hatena 2018/02/15 10:04
プログラム書くうえでも同じ気がする。
61jiro68@hatena 2018/02/15 10:09
良い記事。アジャイルだろうがWeb開発だろうが、そのシステムが停止するまで一切の記憶を失わずに面倒を見続ける覚悟が無いならドキュメントはちゃんと整備する事は必須。
62hdampty7@hatena 2018/02/15 10:14
一度、実際に書かれた設計書を拝見したい。時間さえあればある程度の設計書は書けるようになったと思いますが、やはりこれも、素晴らしい先輩の設計書を参考にさせて頂いたお陰だと思います。
63maname@hatena 2018/02/15 10:14
用語が統一されてないものをOKとしてしまうレビュアをどう教育したら良いか悩むことある
64yuzumikan15@hatena 2018/02/15 10:22
Excel 撲滅運動中なので他企業向けのドキュメントでも Markdown 使うけど、最初にドキュメント内で使うユビキタス言語の定義から書いてた。社内、社外問わず勝手に造語作ってく人なんなのって思う。
65umai_bow@hatena 2018/02/15 10:23
息を吐くように造語する人いますね。たいてい自覚がない
66lalala360@hatena 2018/02/15 10:26
これを守らせる役割の人が必要なんだけど、一から立ち上げる力のある人はどんどん新案件に移っちゃうから、そのうちグダグダになっちゃう。
67rin51@hatena 2018/02/15 10:29
わかりみ。「クリックする」「押下する」とか (押下とは)
68rjge@hatena 2018/02/15 10:31
esaやQiita:Teamで色々共有するときにも役立つやつ。この辺り気をつけて書いてるかどうかで本人以外のメンバーが読んだときの理解ハードルが結構変わる認識。
69awkad@hatena 2018/02/15 10:35
書いてあることはもっともだけど、こういう文体とかばかりにケチつけて、肝心の内容はいっさいレビューしない(できない)おっさんが多いのでなんかなあと思う
70interferobserver@hatena 2018/02/15 10:44
当たり前のことばかりだけど、気を抜くと疎かにしてしまうね。。。
71honeybe@hatena 2018/02/15 11:01
人数多い開発だと用語集が役に立つ時があるが、大体2週間位でみんな言葉に慣れて用語集が更新されなくなり後々入ってきた人が苦労するというよくある光景(何
72teracy_junk@hatena 2018/02/15 11:09
表記ブレとかこそlintでしょと思うわけです
73mate_gai@hatena 2018/02/15 11:16
“できれば、章の見出しだけを書いた状態で然るべき人に見てもらうと、根本的な認識ズレのリスクが減らせます。”
74nil0303@hatena 2018/02/15 11:28
「以上/以下」「より大きい/小さい」はあるあるだけど誤解を与えやすい部分だから、必ず記号(a>b)も併記する。見るときもダメ押してくれないとたまに怖い時がある。
75naglfar@hatena 2018/02/15 11:29
表記ゆれ、「分かればいいじゃん、揃えるなんてめんどくさい」で済ませる人も多いけど、 grep で見つからない時点でとてつもないデメリットだと思う。面倒以外に理由がないなら揃えて欲しい。
76punychan@hatena 2018/02/15 11:40
設計書限定じゃなくて、あらゆる技術文書向け。/でもExcelで書くのやめて。
77odz@hatena 2018/02/15 11:42
用語集マジ大事
78pmint@hatena 2018/02/15 11:43
設計書のスタイルガイド。前世紀のコーディングルールか。用語集は要るけど、他はどうか。主語の統一は、日本語の基本というか欠点でビジネス文章術。/ 設計書は理解が必要なもの。スタイルよりもまず観点が必要。
79d415uk3@hatena 2018/02/15 11:47
"設計書を量産する前にサンプルを作っておく"これは本当に大切。
80aoki789@hatena 2018/02/15 11:47
形式仕様VDMを使うと、バグゼロにできる。おすすめ。導入が大変だけど。
81coolworld@hatena 2018/02/15 11:54
これを教育する時間がとれなくて
82kibitaki@hatena 2018/02/15 11:55
ツッコみたいところあるけど、何しろ言語化できているのしゅごい。俺の場合、バッドノウハウ集のような形でしかルール化というかアウトプットできない。
83ryumachi3@hatena 2018/02/15 12:03
こういうお堅い仕様書のノウハウ、ネット上に全然出てこないから素晴らしい
84naokun776@hatena 2018/02/15 12:10
“アジャイル開発のtipsが多いQiitaの中で、この記事はありがたいです!”/この無邪気なコメントが闇を端的に表わしていて味わい深い
85kamonamban@hatena 2018/02/15 12:19
仕様書に限らず、ナレッジ共有文章の書き方として非常に参考になる
86whiteball22@hatena 2018/02/15 12:21
以前設計書作った時、その時の上司にこの辺は割と指摘受けたなあ。
87ksakae1216@hatena 2018/02/15 12:26
なるほど~。 ちなみにこの記事も読みやすい!!
88choota@hatena 2018/02/15 12:37
もはやドキュメント全般の作成ルールと言っても差支えない!
89mongrelP@hatena 2018/02/15 12:39
エンジニアじゃなくても普通に有用な話だ…
90sigwyg@hatena 2018/02/15 12:42
ごく普通のことだと思ってたけど、なんかべた褒めされてて、けっこう感覚でやってる人多いんだなーって文系的発想。
91itouhiro@hatena 2018/02/15 12:46
「ほとんどは図と表にできる。箇条書き、一文を短く。用語を統一。用語集作る。造語しない(日付関連)。変更履歴の残し方を決める。主語を統一。まず全体像 → 詳細。章立てだけ作り添削を受ける」
92adwhing@hatena 2018/02/15 12:47
すごくいい。デスクに貼っておきたい
93gin0606@hatena 2018/02/15 12:52
設計書だけじゃなくてドキュメントとか文章の書き方みたいな感じだった
94manFromTomorrow@hatena 2018/02/15 13:00
用語集がないのがちょっと気になったかな
95gokichan@hatena 2018/02/15 13:11
すごく当然のことなんだが。これだけブクマをあつめるということは、新人教育とかで教えていない会社が多いんだろうな。
96hiroyuki1983@hatena 2018/02/15 13:31
既存のドキュメントの仕様に合わせるかな。というかドキュメント標準化レビューとかないの?
97mabushii_sign@hatena 2018/02/15 13:39
良い記事。普段なんとなく感じてることがキレイにまとまっている。
98maruyamatk@hatena 2018/02/15 13:53
氷河期世代がすっぽりといないため、こういう知見が失われている現場が多い。
99luccafort@hatena 2018/02/15 14:02
書いてる内容に大きな間違いはないと思うんだけどコメントで絶賛されているのに違和感がある。表記ゆれとか問題もわからなくはないけど本質はそこではないのでは?というこれで開発しやすくなるのか?と疑問。
100keijir@hatena 2018/02/15 14:24
なにこれWord教室?設計書なら要求性能は具体的に数値化するとか。採用するアルゴリズムの候補を実装段階で計測するとか。非機能要件の検討漏れが無いように標準化するとか、エンジニアっぽい事なにも書いてない。
101mather314@hatena 2018/02/15 14:25
開発しやすいかどうかというよりプロジェクト全体で共通認識が作れるかどうかだよね…。この辺は設計だけじゃなくてプロジェクト全体で意識を合わせないと不可能な気がする…。
102sds-page@hatena 2018/02/15 14:35
ベンダーとユーザーで用語統一できてない案件は嫌われる覚悟で厳しく突っ込まないとあとでクラッシュしたときに大事故になる
103golden_eggg@hatena 2018/02/15 14:44
意識的か無意識的かに関わらず、ほんの些細な認識のズレや用語の不統一が大きな不幸を招くの、特に外の会社さんとのやり取りが頻繁な案件ではアルアルなので、webだろうがSIerだろうが関係なく大事な知見だ
104gfx@hatena 2018/02/15 15:25
心がけか…エモいやつかな…と思ってスルーしてたけどテクニック集だった。よい。
105natu3kan@hatena 2018/02/15 15:33
わりと地方で有名なIT企業でも仕事のやり方とか用語の定義の統一化がされてなかったりするからなあ
106privates@hatena 2018/02/15 15:53
造語は作らないには大賛成。ですが理解してくれない人(特に上司)に碎けて説明した造語を独り歩きさせられた事が沢山ある。標準な言葉で会話するのは大変だと、常々思っています。
107Nyoho@hatena 2018/02/15 17:57
いい心がけなのでしっかりブックマーク🔖
108koji28@hatena 2018/02/15 20:34
あとで読むかも
109tbpg@hatena 2018/02/15 21:00
用語集気になっている。ちゃんと管理している場所にいたことがない。ノウハウを知りたい "プロジェクト内で用語集を作りましょう"
110lalupin4@hatena 2018/02/15 21:09
'[glossary] とかタグを付けて、チケット発行しまくりです。
111garage-kid@hatena 2018/02/15 22:35
1091
112raitu@hatena 2018/02/15 23:27
基本の基本の基本、故に超大事
113Wacky@hatena 2018/02/15 23:59
“文章書きの上達のためには、訓練しかありません。 一番大事なのは、身近に厳しく添削してくれる方がいること、だったりします。”
114an_emerald@hatena 2018/02/16 08:16
用語統一、変更履歴…わ か る !!
115rocketboy_miya@hatena 2018/02/16 10:51
用語の統一は退職まで言い続ける覚悟が必要
116k-holy@hatena 2018/02/16 11:24
設計書というか文書の書き方だった。特に用語統一は業種職種関わらず全ての人が気を付けて欲しい。同じ用語が複数の意味で使われていたり、ユーザー側で不適切な用語が蔓延してると設計側としても非常につらい。
117iww@hatena 2018/02/16 18:58
主語と用語の統一は超大事。 おろそかにすると、改変するときに死ぬ
コメント内容の著作権は、投稿者に帰属します。
削除依頼、不適切コメントのご連絡はこちらにお願いいたします。
2018-02-14 12:51:02:1518580262:1527133339
comments powered by Disqus
※メールアドレスは公開されません。
人気の反応