エンジニア歴20数年の私が、設計書を書く際に心がけていること - Qiita
はじめに 時の経つのは早いもので、私がIT業界に身を置いて四半世紀になってしまいました。 その間、膨大な数の「設計書（仕様書）」を書いて来ましたが、未だに悩み・迷いは尽きません。 それでも、亀の甲より年の劫とも申しますので、私なりの経験則を「個人」と「チーム」の両観点でまとめてみました。 本稿のテーマは、「主に設計書を想定した、開発ドキュメントの書き方」です。 本稿で前提とする設計書は、ExcelやWordで書かれた、フォーマルな（≒納品物になりえる）設計文書、です。 したがって、自社サービス開発よりも受託開発、アジャイルよりもウォーターフォール、を前提として読んでいただいた方が、しっくりくると思われます。 ＜ご注意＞ 本稿の内容は執筆者独自の見解であり、所属企業における立場、戦略、意見を代表するものではありません。 個人的に心がけていること 当該文書の作成目的や位置付けを冒頭に記載する
ドキュメント作業で楽をしたい
プログラマがあまりやりたがらない作業のひとつとしてドキュメント作成がよく挙げられるかと思います。 〇〇仕様書とか〇〇設計書とか〇〇手順書などの作成作業ですね。 特に成果物がdocxやxlsxのようなプレーンテキストでない場合、次のような理由で気が滅入る方も多いのではないでしょうか。 手慣れた道具(エディタ)を使うことができない 専用のソフトでよくわからない機能が裏で勝手に動いたりしてて気持ち悪い 変更履歴をトラッキングしづらい、差分をマージしづらい Markdownでさくっと書いてそれっぽいものができれば、GitHubのWikiなどにぼちぼち書き溜めておいて最後にコンパイルするみたいなやり方ができるなぁとか、そうすればわざわざドキュメント専用リポジトリを作ったりする必要もないなぁとかモヤモヤしながらいろいろ調査・検討したので以下の4構成でまとめたいと思います。 Pandocについて Pan
実務に使うプレーンテキスト→Microsoft Word変換、あるいはPandocを使い始めた話 - 技術memo
SIerのお仕事で、設計書を書いたりするときに、Microsoft Office Wordのdocxファイルを使うことがあります。 そんな中でも、ドキュメントのフォーマットがある程度自由にできる場合に*1、Wordで直接書くのをやめて、プレーンテキスト(Markdown)で書いて、Pandocというツールでdocxファイルに変換するようにしてみた、という話です。 動機 何故Wordに直接書くのを止めるのか、という話はいくらでも先例がありそうですが、個人的には以下のあたりが大きいです。 Git等のバージョン管理ツールを使うので、差分が取りやすい形式がよい Wordの入力機能が時々お節介でうざったい、いちいち設定で無効化するのも面倒 GUIであちこちクリックしながら入力したくない、Emacs(またはあなたの好きなエディタ)を使いたい Pandocについて Pandoc - About pand
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
処理を実行中です
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
