20231206_設計ドキュメント腐る問題、Git管理で運用してみた本当のところ設計ドキュメント腐る問題、 Git管理で運用してみた 本当のところ 2023.12.5 真野隼記 ドキュメント管理を制する 陳腐化を防ぐための実践事例 Lunch LT
実装できる人がいない？大丈夫かこの業界 - orangeitems’s diary
最近、何件かの仕事を請けて共通していることがある。頂くドキュメントが非常に良くできているということだ。なぜ作ったか。どのように作ったか。そしてどう運用するべきか。一気通貫に述べられていて読むと非常に勉強になる。 ・・・それなら、このドキュメントを作った人が作ればいいじゃないか、なぜ私の手に次の仕事が来る？。しかもこんな素晴らしいドキュメント付きで。 一つには、このドキュメントとそれを実装することの価値について、読み解ける人がいなくなっている可能性を感じた。どうもベテランと呼ばれていた人たちが定年退職したり、別の仕事をし出している。かといって次世代が育っていない。ドキュメントを読みながら思うのは、書いた人は随分下の方のレイヤーのことをわかっているということだ。クラウドであればオンプレやネットワークのことまで熟知しているということ。 ところが、最近はカタログスペックというか、このサービスを使え
「ドキュメントの書き方」を体系的に学んだことがないエンジニアへ 書籍『エンジニアのためのドキュメントライティング』の概要
インフラエンジニア向けの書籍を取り上げ、著者と出会い、楽しく本を知り、仲間を作る場所である「インフラエンジニアBooks」。ここで、『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』の翻訳を担当した岩瀬氏が登壇。まずは、本書籍の概要について話します。 本セッションの対象者と、セッションのゴール 岩瀬義昌氏：ご紹介いただきました、岩瀬と申します。よろしくお願いします。『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』は、もともと『Docs for Developers: An Engineer’s Field Guide to Technical Writing』という洋書だったんですが、その翻訳をして、今回この機会をいただいています。 余談ですが、APC（株式会社エーピーコミュニケーションズ）さんが「カプセルト
破綻したドキュメント管理、増え過ぎたプロダクトバックログ… 「Jira」「Confluence」などの活用失敗から学ぶツール運用のコツ
Jira SoftwareやTrelloなどを中心としたPMが経験してきたプロダクト管理ツールの失敗や改善を語る「本当に使いこなせてる？プロダクト管理ツールの失敗&改善PMトーク【開発PM勉強会 vol.20】」。ここで株式会社ビズリーチの菊池氏が登壇。ドキュメント管理とプロダクトバックログの失敗から学ぶツール運用のコツについて紹介します。 菊池氏の自己紹介 菊池信太郎氏（以下、菊池）：ビズリーチの菊池から、10分枠で話をします。今日のテーマは「失敗から学ぶドキュメントとチケット運用のコツ」ということで、今まで経験したところで「こういうアンチパターンがあったよ」「こういう改善をしたよ」というようなところをお話しできればと思っています。 自己紹介を軽くすると、（私は）2018年からビズリーチで働いています。ビズリーチサービスを作っていて、プラットフォーム開発部の部長をしています。また、201
良いドキュメントを書きたくなる本を読んだらドキュメンタリアンになりたくなった - じゃあ、おうちで学べる
ドキュメンタリアンとは、役職に関係なく、ソフトウェア業界でドキュメントとコミュニケーションに関心を持つ人のことです。 www.writethedocs.org はじめに これは主に『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』の書評です。私はSreakeにてSREという役職についています。SREはサービス概要、アーキテクチャの解説や図、各種構成図、各種手順書、ポストモーテム、ポリシー、SLA(SLO) … その他の様々な場面でドキュメントを書く必要があります。しかし、ドキュメントは価値が見えにくく時間と労力がかかり品質担保の面で重要度がとても高いのにその場での価値が見えにくいので浸透しにくいです。そのため、エンジニアとしてモチベーションが保ちづらいです。2021年 State of DevOps 2021 にもドキュメントに関する言及があり今後、
コーディングのようにノートを取る技術 - Qiita
はじめに 何かを学習するとき、ノートを取っているでしょうか？ 小学生の頃や中学生・高校生の時の「ノート」は紙に手書きだったかと思います。 しかし、最近になってからはパソコンを使ってノートを取る、という選択肢が増えました。 その変遷の中で生まれたパーソナル・ナレッジ・マネジメント(Personal Knowledge Management) という考え方があります。 その考え方を共有できたらと思います。 直感的なデジタルノート術の原罪 ケース1: ひたすらに手を動かす 学生の頃、黒板に書かれた内容をそのまま必死にノートに写している人がいたのを覚えていますか？ また、その人は成績が高かったでしょうか？ たいていの場合、成績は乏しい人が多かったと思います。自分もそのタイプでした。 手を動かすだけのノート術の不幸な点は、「考える」というアクティビティが行われないため、本当の意味で筋肉を動かすだけと
[Doc] 要件定義書テンプレート・要件定義書の書き方 - Qiita
下記ドキュメントバージョンに関する注意点です。 バージョン番号のルールを定める：バージョン番号は、どのようにつけるかルールを定め、チーム全員が同じ理解で使用するようにする必要があります。たとえば、変更内容によって数字がどのように増えるか（major, minor, patch）、何桁で表現するかなど、具体的に決めておくことが重要です。 変更履歴を明確にする：どのような変更があったのか、それがどのバージョンで実施されたのかを明確にすることが必要です。これにより、何らかの問題が発生した場合に、どのバージョンから問題があるのか特定することができます。 ドキュメントの保存場所を一元化する：ドキュメントのバージョン管理には、ドキュメントを保存する場所を一元化することが重要です。それにより、異なるバージョンのドキュメントが、複数の場所に分散してしまい、誤ったバージョンが使用されることを防ぐことができま
![[Doc] 要件定義書テンプレート・要件定義書の書き方 - Qiita](https://cdn-ak-scissors.b.st-hatena.com/image/square/d7d131e38e26f54466aece3306435a4c09990de8/height=288;version=1;width=512/https%3A%2F%2Fqiita-user-contents.imgix.net%2Fhttps%253A%252F%252Fcdn.qiita.com%252Fassets%252Fpublic%252Farticle-ogp-background-412672c5f0600ab9a64263b751f1bc81.png%3Fixlib%3Drb-4.0.0%26w%3D1200%26mark64%3DaHR0cHM6Ly9xaWl0YS11c2VyLWNvbnRlbnRzLmltZ2l4Lm5ldC9-dGV4dD9peGxpYj1yYi00LjAuMCZ3PTk3MiZoPTM3OCZ0eHQ9JTVCRG9jJTVEJTIwJUU4JUE2JTgxJUU0JUJCJUI2JUU1JUFFJTlBJUU3JUJFJUE5JUU2JTlCJUI4JUUzJTgzJTg2JUUzJTgzJUIzJUUzJTgzJTk3JUUzJTgzJUFDJUUzJTgzJUJDJUUzJTgzJTg4JUUzJTgzJUJCJUU4JUE2JTgxJUU0JUJCJUI2JUU1JUFFJTlBJUU3JUJFJUE5JUU2JTlCJUI4JUUzJTgxJUFFJUU2JTlCJUI4JUUzJTgxJThEJUU2JTk2JUI5JnR4dC1hbGlnbj1sZWZ0JTJDdG9wJnR4dC1jb2xvcj0lMjMyMTIxMjEmdHh0LWZvbnQ9SGlyYWdpbm8lMjBTYW5zJTIwVzYmdHh0LXNpemU9NTYmcz01MjE0ZDhhMTY1ZjE1ODIxNGE5NzU4Njc3MTNjOTBmNg%26mark-x%3D142%26mark-y%3D57%26blend64%3DaHR0cHM6Ly9xaWl0YS11c2VyLWNvbnRlbnRzLmltZ2l4Lm5ldC9-dGV4dD9peGxpYj1yYi00LjAuMCZoPTc2Jnc9NzcwJnR4dD0lNDBzeWFudGllbiZ0eHQtY29sb3I9JTIzMjEyMTIxJnR4dC1mb250PUhpcmFnaW5vJTIwU2FucyUyMFc2JnR4dC1zaXplPTM2JnR4dC1hbGlnbj1sZWZ0JTJDdG9wJnM9MTc4MmM0MTlmNzhiYTJjNTk0ODYwZmExZDc0OWYzNjQ%26blend-x%3D142%26blend-y%3D486%26blend-mode%3Dnormal%26s%3Db088349e276a1ebcdb9dcf1e2d753094)
ドキュメントに固執せよ - gfnweb
どうして人間集団はこんなにも知見の共有を円滑にできないのか？ 改善にはドキュメントにまつわる各個人の心構え・制度設計・技術的解決の全部が必要だという話をしたい． ここでテーマにしているのは，著名OSSなど世の中にいくらでも知見が転がっている対象ではなく，特に企業内の十数人のチームでクローズドに開発しているなどして集合知に頼れない状況下でのドキュメントについてである． 非常に乱暴な言い方をするなら，「コードとか大部分は誰でも書けるようになるものなんよ，そんなところにマッチョイズムとか感じなくてええねん，我々の知的体力や組織性が真に試されるのはドキュメントちゃうんか」という気持ちです — 画力・博士号・油田 (@bd_gfngfn) June 3, 2022 ドキュメントに書く内容の必須項目或るシステム（ソフトウェアなど）について，そのシステムのことを全く知らない人を想定読者としたドキュメント
わかりやすいシステム構成図の書き方 - Qiita
わかりにくいシステム構成図とは こんなシステム構成図を書いてないでしょうか？ このシステム構成図のわかりにくい点が３つあります。それは 製品名は書いてあるが「役割」が書いていない データと処理が区別できない データの流れと制御の流れが区別できない の３つです。 わかりやすいシステム構成図 これら３つのわかりにくい点を改善したわかりやすいシステム構成図が↓です ポイントを解説していきます ポイント1. 製品名称ではなく「役割」を書く システム構成図には製品名称ではなくシステムコンポーネントの「役割」を書きます。 役割とは、例えば〇〇データや〇〇処理といったことであり、それを読むだけでシステムの動きを理解できる文字列です。役割をかかずに製品名称のみを書いてしまうと、その製品を知らない人が見たときに理解できません。例えば「Cloud Pub/Sub」という製品はGCPというパブリッククラウドの分
HTTPキャッシュに学ぶ、無理のないドキュメント更新運用
LAPRAS株式会社でSREをしていますyktakaha4と申します 🐧 私は 2021 年の 1 月に LAPRAS に入社 したのですが、 入社以来ほそぼそとやってきた、ドキュメンテーションに関する取り組みについて一年ほど運用し一区切りがついたので、その話をしたいと思います✍ ことのおこり 現在弊社には正社員・業務委託あわせて 18 名程度のエンジニアが在籍 していますが、 私が入社した頃はエンジニアが7名程度、かつ全体の人数に対して在任歴の長い人が多かったこともあり、 開発者が参照するドキュメント管理について、比較的牧歌的な運用がなされていました 🐑 具体的には、開発環境の構築方法が古い手順のまま放置されていたり、オンボーディングに使うドキュメントが口伝されていたりと、 ドキュメント自体は存在するものの、それらが 古くなっていたり一覧化が不十分であることが検知できず、時間経過に伴
【翻訳】Googleのエンジニアがソフトウェア開発する時に必ず書くドキュメント「Design Docs at Google」 - BppLOG
Googleでの「Design Docs」とは 2007年の Google Developer Day Tokyo での鵜飼氏のプレゼンによると「Google で必ず書くことになっているドキュメント」であり、「プロジェクト立ち上げ時の 1～2週間をかけて書く」ものです。 今回は Google のソフトウェアエンジニアである @cramforce 氏が自身のブログで「Googleでの Design Docs」について解説している記事を公開されていたため、氏の許可を得て翻訳しています。 原文： www.industrialempathy.com 関連書籍： Googleのソフトウェアエンジニアリング ―持続可能なプログラミングを支える技術、文化、プロセス オライリージャパンAmazon 読了目安：11分 (目次) デザインドキュメント の解剖学 文脈と範囲 目標と非目標 実際のデザイン システ
仕様書の参考例と、こんな内容を仕様書に最低書くといいというお話｜田辺めぐみ
よく、仕様書を書いていなくて、書いてみたいけど、具体的な仕様書がネット上に落ちてなくってこまってるって相談を受けるので 「仕様書の記載内容のイメージ」を作りました！ ※前提として「現在仕様書を書いていない、自社開発のMVP検証前後のフェーズのスタートアップ向け」に書いています。PMが仕様書、エンジニアがDesign Docを書く分担です。 ついでに、システム開発の基礎である「システム開発のV字モデルをベースにした設計書の紹介」も含めてまとめてみましたー！ 大規模開発に使われたり、古くからあるフレームワークなので、スタートアップの方だと、システム開発のV字モデルの概念やそれにあわせた成果物を知らない人が多いけど、「要件定義書」と「設計書」を全てドキュメント化するとどうなるかを理解した上で、「仕様書」として情報を削る方が、考慮漏れ防止やエンジニアがやっている設計内容の理解につながるので、全体を
「次から気をつけます」に対抗する、反省文よりは効果が上がる再発防止、学びの機会 - Qiita
再発防止策を書くのは難しい。 良い再発防止策 良い再発防止策について、順位付けするとしたら、 その種類の問題について二度と意識することがなくなる解決策 その種類の問題を開発時に自動的に検知することができる解決策 その種類の問題が発生しても自動的に復旧することができる解決策 その種類の問題が発生しても影響が局所化される、フールプルーフ、フェールセーフになる解決策 と言うのは意識したいと思いつつ、やはり難しい。 再発防止はむずかしい 障害の再発防止策は、 メカニズム ツール ルール チェックリスト の順番に検討せよ。と言われても、急いで書けなんて言われると「次回からは複数人でチェックします。」とか「チェック項目を追加します。」とかいう徹底できなそうな「反省文」になってしまう。 まさにこの有名な猫...。 **「なぜミスを繰り返すのか」「どうすればミスを防げるのか」を真剣に考えていないことがミス
自己流の手順書フォーマットを公開してみた | DevelopersIO
手順書フォーマットは千差万別 みなさんは自己流または、組織やプロジェクトで定められた手順書のフォーマットはありますか? 私は自己流の手順書フォーマットがあります。 自己流の手順書フォーマットがあるといっても、かなり扱いがふわふわしているので、備忘やメモの意味合い強めでまとめていきます。 「もっとこうした方がいいよ!!」などフィードバックがあれば、ぜひお願いします! いきなりまとめ 手順書はExcelやスプレッドシートではなく、Markdownで書く 手順書はgitで管理する 5W1Hを意識して手順書を書く 基本的にはCLIを使った手順書にする 手順書はExcelやスプレッドシートではなく、Markdownで書く 手順書をExcelやスプレッドシートで書くメリット・デメリット 手順書をExcelやスプレッドシートで書いている方も多いと思いますが、私はMarkdownで書いています。 Exce
プログラマーがドキュメントを書かない理由
この記事は、著者の許可を得て配信しています。 Why programmers don’t write documentation 最近ではずっとコードのドキュメンテーションに関連した記事を書いていたので、当然、私のMediumのおすすめ記事には「開発者がドキュメントを書かない本当の理由」という記事が表示されるようになりました。この記事では、ドキュメントを書くための優れたツールがないことが、ソフトウェアエンジニアが自分の作業や判断をドキュメンテーションする意欲を失わせる最大の原因について書いています。 私は普段、特定の記事を批判したりはしませんが、この記事には怒りを覚えました。このライターは図解ツールについていくつかメリットに関して述べてはいますが、全体的に誤解を招くような内容になっており、この重要な問題をより分かりにくくさせています。2つの図解ツールを比較して、どちらも不十分なツールである
プログラムの「アーキテクチャに関するドキュメント」は面倒でも書くべき、ではどのように書くべきか？
開発プロジェクトに新しく加わった時は、まずプロジェクトの理解が第一。しかし、全体像を把握できるようなドキュメントがなく、コードから断片的な情報をかき集めるしかない場合もあります。新参の開発者がスムーズにプロジェクトを理解できるよう、大規模なプロジェクトでは「プロジェクト全体のアーキテクチャ」を示した「ARCHITECTURE.md」を添えた方がよいと、エンジニアのAleksey Kladov氏が指摘しています。 ARCHITECTURE.md https://matklad.github.io//2021/02/06/ARCHITECTURE.md.html Kladov氏はオープンソースプロジェクトの開発に携わる中で、「プロジェクトのアーキテクチャに対する知識量」によって開発スピードに大きな差が生じると気づいたとのこと。アーキテクチャに関する知識がない開発者にとって、大量のコードは「バラ
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
Google社のテクニカルライティングの基礎教育資料がとても良かったので紹介したい - Qiita
はじめに エンジニアにとって、仕様書などの技術的な文章を書くこと（テクニカルライティングとも言います）は避けて通れません。ただ20年来多くのエンジニアの方々と同僚として接してきて思うことは、エンジニアの方の中には「文章を書く」ということに苦手意識がある方が一定数いるということです。 でもこの「テクニカルライティング」のスキルは、才能というよりは一種の「技能」だと思うんです。ある一定の原理原則を理解して実践を繰り返すことで、必ず一定レベルで習得できるものだと著者は信じています。 もしこのテクニカルライティングの原理原則をまだ体系的に学習したことがない、または過去学習したが改めて再学習したいという方に、お勧めのコンテンツを見つけたのでご紹介します。 https://developers.google.com/tech-writing Every engineer is also a write
ドキュメント作成スキル向上を目指す人向けおすすめ記事まとめ - Qiita
システム開発にドキュメントは欠かせません。ドキュメントが得意になれば活躍の幅が大いに広がりますよね。 この記事では、まず冒頭でドキュメントの作成に求められると思うことを整理した上で、そのスキル獲得に役立つと思われる記事や書籍を集めてみました。もちろん他にもあると思うので、もしお薦めのものがあれば是非コメントで教えて下さい 更新履歴 ・2021/04/16：文章術系にリンクを追加しました。 ・2020/11/28：文章術系にリンクを追加しました。 ・2020/07/24：文章術系にリンクを追加しました。 ・2020/05/24：文章術系にリンクを追加しました。 ・2020/05/14：スライドデザイン系にリンクを追加しました。 ・2020/04/29：スライドデザイン系にリンクを追加しました。 ・2020/04/17：文章術系にリンクを追加しました。 ・2020/04/12：関連するTwit
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
テクニカルライティングの基本
