設計ドキュメント腐る問題、Git管理で運用してみた結果 | フューチャー技術ブログ
はじめにTIG真野です。 秋のブログ週間2023 の3本目は、設計ドキュメントをGit管理して腐らせないようにがんばってみた話をします。 前段として6年前、「我々はいかにシステム開発におけるドキュメント腐る問題と戦えば良いのか」という記事を書いたのですが、その後の試行錯誤はどこにも残していないことに気づきました。普段のフューチャー技術ブログですとちょっと引け目を感じるテーマですが、秋の夜長を楽しむため読み物成分を多めに書くというテーマのこのブログリレーにピッタリな気がするため、この機会をお借りします。 ドキュメントも色々な種別があるかと思いますが、この記事では設計ドキュメントを指すことにします。設計ドキュメントは開発メンバーが参照するもので、ステークホルダーへの説明資料に引用して使うことはあれど、主目的は異なるという前提です。Design Docの場合もありますし、システム構成図、ERD、
ユーザーはドキュメントを「読みにくるけれど読んでいない」 “流し読み”しやすいドキュメント作成のポイント
インフラエンジニア向けの書籍を取り上げ、著者と出会い、楽しく本を知り、仲間を作る場所である「インフラエンジニアBooks」。ここで、『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』の翻訳を担当した岩瀬氏が登壇。さらに、ドキュメントの具体的な書き方と、フィードバックの収集について話します。前回はこちらから。 ドキュメントは「書き始める」ことが大事 岩瀬義昌氏：3章にいきます。時間的にあと15分ぐらいしゃべっても大丈夫かな？ 10分ちょっとしゃべれると思うので。（スライドが）あと70枚あるので、すごく速くいきますね（笑）。 ドラフトの執筆です。みなさんもドキュメントを書くじゃないですか。ちょっと胸に手を当てて（考えて）みると、ドキュメントを書く上で、一番難しいことは何だと思いますか？ （スライドを示して）書ける人は良いんですが、最初の人が1文字目を書き
ARCHITECTURE.mdというものを書いてみた - maru source
こんにちは丸山@h13i32maruです。システム全体を簡単な図とテキストでまとめる「ARCHITECTURE.md」というものを最近知りました。これは良さそうと思い、JasperのARCHITECTURE.mdを書いてみました。 jasperapp/jasper/ARCHITECTURE.md ARCHITECTURE.md自体の目的は「プロジェクトへの新規参加者が全体像の把握を効率的に行えるようにする」という感じです。書き方の指針や注意点などは考案者による記事を見てもらうのがよさそうです。また良いサンプルとしてrust-analyzerというOSSのARCHITECTURE.mdが紹介されています。 https://matklad.github.io//2021/02/06/ARCHITECTURE.md.html https://github.com/rust-analyzer/ru
プログラムの「アーキテクチャに関するドキュメント」は面倒でも書くべき、ではどのように書くべきか？
開発プロジェクトに新しく加わった時は、まずプロジェクトの理解が第一。しかし、全体像を把握できるようなドキュメントがなく、コードから断片的な情報をかき集めるしかない場合もあります。新参の開発者がスムーズにプロジェクトを理解できるよう、大規模なプロジェクトでは「プロジェクト全体のアーキテクチャ」を示した「ARCHITECTURE.md」を添えた方がよいと、エンジニアのAleksey Kladov氏が指摘しています。 ARCHITECTURE.md https://matklad.github.io//2021/02/06/ARCHITECTURE.md.html Kladov氏はオープンソースプロジェクトの開発に携わる中で、「プロジェクトのアーキテクチャに対する知識量」によって開発スピードに大きな差が生じると気づいたとのこと。アーキテクチャに関する知識がない開発者にとって、大量のコードは「バラ
マネジメント業を通じて考えた、プロジェクト全体像の認識齟齬を防ぐ誤解されないドキュメント作成術 - ANDPAD Tech Blog
アンドパッドの土方です。 本ブログではEMインタビューで取り上げておりますが、記事投稿は初めてです。 エンジニアマネージャーとしてのイベント登壇や、プロジェクト推進における案件の取りまとめ業務が増えてきており、それに伴ってドキュメントを作成する機会も増えてきました。 自分の考えを整理するとともに、アンドパッドのエンジニアにはこんなこと考えている人もいるよ、的な意味で紹介したいと思います。 何かの参考になれば幸いです。 結論！ 次項からは文字ばっかりで語っているだけになりますので先に結論を書きます。 断面を作るための切り方を意識する 網羅性、単一性を守る 二軸で表現する この三項を守ることで、理解されやすく誤解を招かないドキュメントの完成に近づけると考えています。 ではここからだらだら語ります。 ドキュメントの目的は？ そもそもドキュメントはなんのために作るものでしょうか。 私は、「認識を合
ドキュメントを書くときの「メンタルモデルの原則」 - クックパッド開発者ブログ
こんにちは。クリエイション開発部の丸山@h13i32maruです。 みなさんドキュメント書いてますか？私はドキュメントを書くのは結構好きです。最近もプライベートで開発しているJasperというGitHub用Issueリーダーのユーザ向けドキュメント（マニュアル）を書きました。でも良いドキュメントを書くのって難しいですよね。 そこで、本記事では「ツールやライブラリなどを対象にしたユーザ向けドキュメント」を書くときに私が考える原則を紹介します。ちなみに私はテクニカルライティングの専門家ではなく、普通のソフトウェアエンジニアです。そのあたりはいい感じに汲み取っていただけると🙏 🕵️メンタルモデルの原則 良いドキュメントとはどのようなものなのでしょうか？私は「そのツールやライブラリに対して読者がメンタルモデルを構築できる」のが良いドキュメントだと考えています。これを「メンタルモデルの原則」と呼
人間の失敗を記したドキュメントは陳腐化しない - しゅみは人間の分析です
SRE本を読んでからポストモーテムについて考えている。ポストモーテム（post-mortem）とは反省会、事後検討といった意味の言葉である。つまり、なにか予期せぬ失敗をしたときに書く文章だ。SRE本ではサーバシステム運用の文脈で使われた。 仕事でドキュメントは大事だ。喋って何かを決めたり、ふりかえっても、文章で蓄積しないと何も残らない。われわれソフトウェアエンジニアがよく書くのは、設計とか仕様についてのドキュメントだろう。だが、これらのドキュメントはしばしば陳腐化する。特に、仕様やソフトウェアの使い方、環境構築のドキュメントはすぐに内容が古くなる。こうしてわれわれは文章を書かなくなるのだが、どうやらポストモーテムは違う性質を持っている。 というのも、失敗を記録した文書は陳腐化しにくいのだ。なぜなら、過去に起こった事実を記録しているから。過去に起こったことを記述するので、原理的に内容を書き換
保守開発者向けのソフトウェア設計書は必要か？ - 勘と経験と読経
前回公開したエントリ「開発者向けのソフトウェア設計書は必要か？ - 勘と経験と読経」へのフィードバックで、保守には設計書が必要なのではないか、というものがあった。その点については思うことがある。というわけで、保守という観点でソフトウェア設計書に関する考えをまとめてみた。ソフトウェア構築時に必要とされる設計書と、保守の際に必要とされるものは異なるのではないかと考えている。 議論の前提：仕様書と設計書 再掲になるけれども、ここでは仕様書と設計書という用語を以下のように定義する。 仕様書 … 開発者とユーザー(仕様決定者)が、ソフトウェアの振る舞いや動きに関してコミュニケーションするために必要な文書類のこと。 設計書 … 開発者どうしがソフトウェアを作成するにあたっての、構造や仕様についてコミュニケーションするために必要な文書類のこと。 そして、改めて説明する必要は無いと思うけれども仕様書は保守
我々はいかにシステム開発におけるドキュメント腐る問題と戦えば良いのか
フューチャーアーキテクト Advent Calendar 2017 の2日目です。 システム設計が大好きで大嫌いな皆さん、こんにちは。 突然ですが、皆さんはどのようにシステム設計における ドキュメント腐る問題 に立ち向かっていますか？ … ドキュメント腐る問題とは、設計時に作成した各種ドキュメントがGoogle Driveやファイルサーバ上で陳腐化してしまい、現状の正しい状態を指していないことです。せっかく新規参画者がキャッチアップしようとしてもドキュメントが真実を示していないという怖いやつですよね。 今まで出会った一番辛いドキュメントは、PJ初期に作成したホワイトボードに書かれたラフスケッチの画像しか無かったところですね。まず字が汚いし、内容も最新版と微妙に異なっていました。新規参画者殺しにもほどがあると、ほんのちょっとだけ恨みました。 いやいや、ちゃんとサボらず整合性を取れよって？サボ
Design Docs at Google
One of the key elements of Google's software engineering culture is the use of design docs for defining software designs. These are relatively informal documents that the primary author or authors of a software system or application create before they embark on the coding project. The design doc documents the high level implementation strategy and key design decisions with emphasis on the trade-of
ドキュメントとコードが乖離しないように DMM .com のエンジニアが教えるGoaを使ったAPIサーバーの作りかた
DMM Groupのエンジニアが、Goを活用したプロダクト事例やトレンド、現場のリアルを話すイベント「DMM.go」。2回目の今回は、DMM.com プラットフォーム事業本部 エンジニアの本田雄亮氏が、Goaを使ってAPIサーバーを作る方法について紹介しました。関連資料はこちら。 手作業のドキュメントとコードとは乖離する 本田雄亮氏：今回、「Goaを使ってAPIサーバー開発してみた」というタイトルでお話ししたいなと思います。 まず自己紹介です。プラットフォーム部というところで基盤システムの開発をしています。バックエンドのエンジニアです。名前は本田です。興味あるのは、Goとかアーキテクチャ。DDDとかがけっこう好きなので、もし懇親会に参加される方がおられたら、Goaだけの話じゃなくて、Go全般だったりアーキテクチャ、DDDまわりでもお話できたらなと思っています。 さっそくメインテーマのGoa
執筆活動を支える技術 #ruby超入門 - Qiita
「ゼロからわかる Ruby🔰超入門」という本を書きました。共同執筆での作業を効率的に進められるように、編集者・レビュワーさんを含め、みんながいつでも最新の原稿を確認できるように環境を整えました。ここでは、技術面・環境面で工夫したこと、得た知見を共有します。書籍に限らず、技術文書の作成にも使えます。 はじめに この本は、 @igaiga さんと共同で執筆しました。イラストを描いてくれた @becolomochi さんを含めて、3人での共同作業でした。原稿を書いてから公開するまでのフローはこんな感じです。プログラミングでの開発に似ています。 原稿を書く (Asciidoc, Atom, Visual Studio Code) 共有する (GitHub, Slack) HTML/PDF形式に変換する (Rakefile, CircleCI) 限定公開する (docker, nginx) Ste
“設計思想書”で開発の効率と質を高めよう
システム開発を効率化するために、過去に開発した資産の“流用”がよく行われている。エクスプレス開発の場合、最初から“再利用”を前提に開発を行い、その“開発思想”を記録として残すことで、より積極的に既存資産を活用する。 前回『“すべてを任せてもらえる「専門家」になろう 』では、顧客企業との打ち合わせの早い段階で、SEが「専門家」と認められれば、スケジュールを含めたあらゆる提案が受け入れられやすくなる──すなわち短納期化に貢献する、といったことを解説しました。 ただ、これは短納期化に不可欠な要素ではありますが、直接的に寄与するわけではありません。短納期化には、もっと具体的な考え方や方法論、そして、日ごろからの準備や工夫が必要なのです。今回は、そうした短納期化の方法論の1つとして、「システムの再利用」について解説したいと思います。 “流用”と“再利用”は違う SEやベンダのスタッフは「過去の開発資
正常系と異常系の区別とドキュメントの書き方について - ウィリアムのいたずらの、まちあるき、たべあるき
ウィリアムのいたずらが、街歩き、食べ物、音楽等の個人的見解を主に書くブログです（たま～にコンピューター関係も） 正常系と異常系について、テストの観点から書かれているものが多い。 そして、区別が曖昧なものも多いです。 ところが、ソフトウェア工学の観点から見ると、これは、明確に分かれます。 →ユースケース記述で そして、開発上、重要な意味を持つので、ちょっと所見を書いてみます。 ■正常系とは ＜＜ソフトウェア工学的には：たぶん＞＞ ・事前条件が成立するときに、事後条件が成立するケースが正常 ＜＜解説＞＞ ある処理に対して、入力値が適切であるとき、 処理終了後の状態が、期待している通りになっているもの →期待している成果物ができている状態 ■正常系でないとは ＜＜ソフトウェア工学的には：たぶん＞＞ ２とおりある ・事前条件が成立しないケース ・事前条件は成立するが、事後条件が成立しないケース ＜
エンジニア歴20数年の私が、設計書を書く際に心がけていること - Qiita
はじめに 時の経つのは早いもので、私がIT業界に身を置いて四半世紀になってしまいました。 その間、膨大な数の「設計書（仕様書）」を書いて来ましたが、未だに悩み・迷いは尽きません。 それでも、亀の甲より年の劫とも申しますので、私なりの経験則を「個人」と「チーム」の両観点でまとめてみました。 本稿のテーマは、「主に設計書を想定した、開発ドキュメントの書き方」です。 本稿で前提とする設計書は、ExcelやWordで書かれた、フォーマルな（≒納品物になりえる）設計文書、です。 したがって、自社サービス開発よりも受託開発、アジャイルよりもウォーターフォール、を前提として読んでいただいた方が、しっくりくると思われます。 ＜ご注意＞ 本稿の内容は執筆者独自の見解であり、所属企業における立場、戦略、意見を代表するものではありません。 個人的に心がけていること 当該文書の作成目的や位置付けを冒頭に記載する
開発のドキュメントをどこに置くか問題 - $shibayu36->blog;
最近開発用のドキュメントをどこに配置するか悩んでて、いくつか試して見てる。今回言っている開発用のドキュメントというのは、コードの触り方も含んだサービスの開発に関するもの。例えば 開発環境セットアップ方法 ページに表示している広告をどのように切り替えたりするか(googleの管理やコードの変更も含めた) サービス内の特定の機能の仕組み 内部用HTTP APIドキュメント などを指している。 結構いろいろ考えるところがあるので、思っていることをまとめてみたい。一応先に結論を言っておくと 基本は実装に一番近いところにコメントとしてドキュメント書くのが良いと思う いろんなパーツが絡みあうような大きな機能の場合、導入部分だけ別の場所に書く 出来るだけrepository内に入れておくと探しやすく、更新しやすいと思う あといろいろ悩んでるので事例あったら教えてください。 起きている問題 ドキュメントは
クラウド時代に求められる 「実行可能な仕様書」とは？
Excel方眼紙の問題 業務システム開発の世界には「Excel方眼紙」と多少軽蔑的に呼ばれるものがある。行間と列間を細かく設定したExcelシートのことで、さまざまなドキュメントの汎用様式とされる（図1）。特にソフトウェアの「仕様書」を書くために多用されている。 表計算ソフトはもともと表形式の数値計算や、これに付随する文字列操作に特化したソフトウェアだ。にもかかわらず、日本においては文書作成や仕様書を書くためのツールの“デファクトスタンダード”と言っても良いほどに「Excel方眼紙」は普及している。罫線へのこだわりと同様に、これはどうも日本だけでの現象らしいことから、一部では、日本の「格子偏愛文化」が生んだものではないかとも推測されているようだ。 Excel方眼紙上で仕様書を作成するのは面倒ではあるが、セル結合やフォント指定を駆使すれば思った通りにまとめられるし、印刷してもそれなりにキレイ
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
