はじめに 時の経つのは早いもので、私がIT業界に身を置いて四半世紀になってしまいました。 その間、膨大な数の「設計書(仕様書)」を書いて来ましたが、未だに悩み・迷いは尽きません。 それでも、亀の甲より年の劫とも申しますので、私なりの経験則を「個人」と「チーム」の両観点でまとめてみました。 本稿のテーマは、「主に設計書を想定した、開発ドキュメントの書き方」です。 本稿で前提とする設計書は、ExcelやWordで書かれた、フォーマルな(≒納品物になりえる)設計文書、です。 したがって、自社サービス開発よりも受託開発、アジャイルよりもウォーターフォール、を前提として読んでいただいた方が、しっくりくると思われます。 <ご注意> 本稿の内容は執筆者独自の見解であり、所属企業における立場、戦略、意見を代表するものではありません。 個人的に心がけていること 当該文書の作成目的や位置付けを冒頭に記載する
はじめに 同人活動の形態としては、本業を持ちながら趣味の範疇で細々と同人活動を行う、というスタイルが多くみられる。かく言う私もその中の一人だ。 ところで、情報産業に勤めながら同人活動を行っている人は少なくない数いると私は考えている。(実際どうかはさておき。) そういう人達にとって、同人活動を行う上での敷居を嵩上げしまくっている要因がある。 それは無論、本業の収入だ。 IT関連のエンジニアはとにかく安月給なのである。 安くかつ長く働かせる(事により残業代で稼いでもらう)というのが我が業界の基本スタンスだ。どうしようもなくクソであるが、それはまぁ今回は置いておく。 そういった人達にとって、設備投資は常に悩みの種。できればしたくはないというのが本音だろう。 その場合、一番困るのが「どうやって『組版(印刷所に提出できる形式の原稿を作成すること)』するか」という事だと思う。 大手(壁サーとかお誕常連
TL;DR Wordは箇条書きを作る度に膨大な情報がコピーされ、それは元の箇条書きを消しても残る(Windows/Mac共通) Wordは文章を編集するたびに、中身が断片化する。一度断片化したら元には戻らない(Mac版のみ) 断片化、参照されていない箇条書き情報については「名前をつけて保存」しても解消しないが、「全て選択してコピー、新規作成したファイルに貼り付け」で解消する。 2018年9月19日追記 本稿にはもともと「Windowsで作成したWordファイルをMacで修正すると断片化する?」という仮説が追記として掲載されていましたが、実際には「作成環境に関係なく、Mac版Wordで編集すると断片化する」ことがわかりましたので、後で読む方の混乱を避けるためにその追記を削除しました。 はじめに Wordファイルを扱っていて「だんだん重くなっていく」と感じたことはないだろうか。特に、代々引き継
プログラマがあまりやりたがらない作業のひとつとしてドキュメント作成がよく挙げられるかと思います。 〇〇仕様書とか〇〇設計書とか〇〇手順書などの作成作業ですね。 特に成果物がdocxやxlsxのようなプレーンテキストでない場合、次のような理由で気が滅入る方も多いのではないでしょうか。 手慣れた道具(エディタ)を使うことができない 専用のソフトでよくわからない機能が裏で勝手に動いたりしてて気持ち悪い 変更履歴をトラッキングしづらい、差分をマージしづらい Markdownでさくっと書いてそれっぽいものができれば、GitHubのWikiなどにぼちぼち書き溜めておいて最後にコンパイルするみたいなやり方ができるなぁとか、そうすればわざわざドキュメント専用リポジトリを作ったりする必要もないなぁとかモヤモヤしながらいろいろ調査・検討したので以下の4構成でまとめたいと思います。 Pandocについて Pan
pandocでorg-modeのテキストをWordファイル(docx)に変換しています。 議事録などドキュメントをまとめるのはorg-modeの方が楽ですよね。 (さらにdocxをPagesで開いて、PDFにしています) まずはここを参考に、pandocのテンプレートを取り出します。 PanDoc - catch.jp-wiki pandoc --print-default-data-file reference.docx > reference.docx このreference.docxを編集し、見出し1〜見出し5、箇条書き、箇条書き継続行などを修正しました。 内容はHello, World. となっていますが、pandocはスタイルを利用していて内容を無視しているようです。 なので好きな内容に変更して、好きなスタイルを適用するとよいとおもいます。 上記Wikiの受け売りですが、既存のテ
SIerのお仕事で、設計書を書いたりするときに、Microsoft Office Wordのdocxファイルを使うことがあります。 そんな中でも、ドキュメントのフォーマットがある程度自由にできる場合に*1、Wordで直接書くのをやめて、プレーンテキスト(Markdown)で書いて、Pandocというツールでdocxファイルに変換するようにしてみた、という話です。 動機 何故Wordに直接書くのを止めるのか、という話はいくらでも先例がありそうですが、個人的には以下のあたりが大きいです。 Git等のバージョン管理ツールを使うので、差分が取りやすい形式がよい Wordの入力機能が時々お節介でうざったい、いちいち設定で無効化するのも面倒 GUIであちこちクリックしながら入力したくない、Emacs(またはあなたの好きなエディタ)を使いたい Pandocについて Pandoc - About pand
考えを整理しながらドキュメントを書くのにMarkdownが便利ですが、資料を印刷して持ってきてとか言われると困ったりします。 そんな時にPandocを使ってdocxなどの形式に変換して印刷すると便利です。(PDFにも出来ますが、フォントサイズなどの微調整も出来るのでdocxにすることが多いです) pandocは、Haskell製のドキュメント変換ツールです。 対応している形式などは以下を参照してください。 Pandoc - About pandoc インストール インストールは以下を参考にしてください。PDFへ変換するには別途依存するライブラリを入れる必要があります。 http://johnmacfarlane.net/pandoc/installing.html MacとWindows向けにはインストーラが提供されているので、それを使ってインストールすると楽です。 Releases ·
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
処理を実行中です
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く