網羅的なPRDやDesign Docを書かなくなった - kosui
2024/06/12 16:16 結論を追記 2024/06/12 20:29 より記事の内容を分かりやすく理解頂くため、タイトルを「PRDやDesign Docを書かなくなった」から変更 2024/06/13 20:39 結論にフロー情報・ストック情報に関する意見を追記 結論 この記事では、「様々な観点を考慮して網羅的にドキュメントを書いて、それを関係者にレビューしてもらう」のではなく、関係者と同期的に対話しながら、観点や選択肢やそのトレードオフを洗い出すことで、少ない手数でより良い答えが見つけられると主張する。 ただし、対話のために必要なドキュメントは事前に書いておくべきだし、対話した結果はドキュメントに残すことが望ましい。そして、そのドキュメントのフォーマットはPRDやDesign Doc以外でも良い。例えば、ADRはアーキテクチャに関する議論の過程と結果を述べる上で必要十分なフォー
社内技術ドキュメンテーションを科学する - スタディサプリ Product Team Blog
最終更新日: 2024年02月27日(月) 1. ご挨拶 2. 本記事執筆のモチベーション 3. ワークショップを通じて得たフィードバック 3-1. Pains -過去抱えた/現在進行形で抱えている辛み- 3-2. Approaches/Solutions -Pains を解消するために取った方策や導き出した解決策- 3-2-1. えいやで場所を決め打ちしてしまう(e.g., GitHub Wiki + Google docs しか使わない) 3-2-2. 個人的に、2023/12/05時点で〜みたいな書き方を心がけている 3-3. Tips -効果的な手法- 4. オーディエンスからの反響 4-1. 気づきや学び・NEXT ACTIONS 4-2. プレゼンター(@hayat01sh1da)へのフィードバック 4-3. Slack での反応 5. おわりに 1. ご挨拶 初投稿となります
ADR を1年間書いてみた感想 - 一休.com Developers Blog
宿泊開発チームでエンジニアをしている @kosuke1012 です。チームで ADR を書き始めて1年くらい経ったので、その感想を書いてみたいと思います。 この記事は 一休.comのカレンダー | Advent Calendar 2023 - Qiita の13日目の記事です。 ADRとは アーキテクチャ・ディシジョン・レコードの略で、アーキテクチャに関する意思決定を軽量なテキストドキュメントで記録していくものです。 出典はこちらで、 Documenting Architecture Decisions わかりやすい和訳は以下の記事が、 アーキテクチャ決定レコードの概要 | Cloud アーキテクチャ センター | Google Cloud アーキテクチャ・デシジョン・レコードの勧め | 豆蔵デベロッパーサイト アーキテクチャの「なぜ？」を記録する！ADRってなんぞや？ #設計 -
設計ドキュメント腐る問題、Git管理で運用してみた結果 | フューチャー技術ブログ
はじめにTIG真野です。 秋のブログ週間2023 の3本目は、設計ドキュメントをGit管理して腐らせないようにがんばってみた話をします。 前段として6年前、「我々はいかにシステム開発におけるドキュメント腐る問題と戦えば良いのか」という記事を書いたのですが、その後の試行錯誤はどこにも残していないことに気づきました。普段のフューチャー技術ブログですとちょっと引け目を感じるテーマですが、秋の夜長を楽しむため読み物成分を多めに書くというテーマのこのブログリレーにピッタリな気がするため、この機会をお借りします。 ドキュメントも色々な種別があるかと思いますが、この記事では設計ドキュメントを指すことにします。設計ドキュメントは開発メンバーが参照するもので、ステークホルダーへの説明資料に引用して使うことはあれど、主目的は異なるという前提です。Design Docの場合もありますし、システム構成図、ERD、
〜その意思決定を刻め〜「アーキテクチャ・デシジョン・レコード(ADR)」を利用した設計の記録 - スタディサプリ Product Team Blog
こんにちは。スタディサプリのWeb開発をやっている@highwideです。 今日は、自分の所属する"コーチングチーム"(個別指導コースや合格特訓コースの機能開発を行っています)が、最近のプロジェクトで利用した「アーキテクチャ・デシジョン・レコード」、通称「ADR」について紹介したいと思います。 アーキテクチャ・デシジョン・レコード(ADR)とは 「ADR」「アーキテクチャ・デシジョン・レコード」という概念を知ったのは、社内で行っていた「Design It! プログラマーのためのアーキテクティング入門」(以後「Design It!」)の読書会でのことでした。 www.oreilly.co.jp 最初にそのキーワードが登場する「11.2.3 必要なときだけ形式的な記述に投資する」では、「"膨大な量のドキュメントになる傾向"がある形式的なドキュメンテーション」に対比して、以下のように紹介されます
「ドキュメントの書き方」を体系的に学んだことがないエンジニアへ 書籍『エンジニアのためのドキュメントライティング』の概要
インフラエンジニア向けの書籍を取り上げ、著者と出会い、楽しく本を知り、仲間を作る場所である「インフラエンジニア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
GitHub、あなたの会社にオープンソース担当部門「Open Source Program Office」を立ち上げて機能させるためのドキュメント群をオープンソースで公開
GitHub、あなたの会社にオープンソース担当部門「Open Source Program Office」を立ち上げて機能させるためのドキュメント群をオープンソースで公開 ソフトウェアの開発や運用において、さまざまなオープンソースが重要な役割を果たすようになってきており、現在ではオープンソースを抜きにソフトウェア開発や利用を行うことがほとんど困難な時代になってきました。 オープンソースと適切に関わり、活用や推進をしていくことは、ソフトウェアに関わる企業にとって（それ以外の企業にとっても）戦略的に取り組むべき事項になってきているといえます。 そうした中で「Open Source Program Office」（OSPO）と呼ばれる組織への注目が少しずつ高まっています。 一般的にOSPOとは、企業のオープンソース戦略の策定と実行といった大きなものから、社内でのオープンソースに関する啓蒙と推進、
ソフトウェアエンジニアとしての能力を高める方法について考えてみた - joker1007’s diary
早朝の寝る前ぐらいの時間にぼやっと下記の様なツイートしたらちょっと反応を貰ったので、取り留めは無いが自分なりに考えていることを書いてみる。 人を育てるのも仕事の内というのは完全にその通りなんだが、そこにドキュメントや本があるから読みます、触って作ってみます、生きたコードを読みます、以外に学ぶ方法なんかねえし、知らねえよ。ただやればいいだけの事に説明も何も無いんだよな……。マジ分からん……。— joker1007 (アルフォートおじさん) (@joker1007) March 2, 2023 タイトルは雑に書いたけど、能力を高めるというと範囲が広過ぎるので、技術的な意味でできる事が増える、ということをテーマとして話をしていこうと思う。基本的に自分の考え方の話なのでそこは御留意ください。 ツイートした通りで、状況や対象に依って割合は変わるかもしれないが基本的にそのためにやることは3つしかないと
[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)
納品ドキュメントの作成にMarkdown+Vivliostyleを採用した話 - Qiita
こんにちは、製造業でソフト開発エンジニアをやっているとみー(@tommyecguitar)です。 会社で納品物の説明ドキュメントを作ることがあり、その時にMarkdownでの組版をやってみたので、どう運用したか、困ったところ、いい点、悪い点をまとめてみようと思います。 Vivliostyleで組版したブログはたくさんあるので、見た目がどんな感じにできるかなどはそちらを見ていただくか、Vivliostyleのサイトをご覧ください。 Wordじゃだめなのか。 製造業で何かしら長大なドキュメントを作るとなったら、大抵はWordを複数人数で編集するという運用をしているところが多いと思います。 しかし、Wordにはいろいろと悪いところがあります。 チーム内で共同編集すると、編集したところが消えたり、フォントやデザインがなぜか統一されなかったりする。 セクションごとに担当を分けても、マージが手作業にな
ユーザーなのか、ユーザなのか
ユーザーなのか、ユーザなのか ユーザー、ユーザ サーバー、サーバ リカバリー、リカバリ 皆さんはどちら派でしょうか？ 経緯 ー (長音符)の扱いについて、どちらで統一するか？と言うちょっとした議題が上がりました。 個人的に気になったので、ちょっと深堀してみます。 長音符、長音符号、長音記号とは？ wikipediaによると、以下の内容が記載されています。 長音符（ちょうおんぷ）、長音符号（ちょうおんふごう）、長音記号（ちょうおんきごう）または音引き（おんびき）は、「ー」のように書き表される、日本語の記号（約物）のひとつ。棒引き（ぼうびき）ともいう。 まず、前提として「記号」として扱われるらしい。 カタカナ表記においては 長音符は主にカタカナで外来語（例：テーブル）や擬音・擬態語（例：ニャーン、シーッ）の長音を表記する場合に使われる。 とのことらしい。 では、具体的にどのようなパターンで調音
技術文書の書き方
howto-tech-docs.md 技術文書の書き方 このメモは、私（@ymmt2005）が長年にわたってソフトウェアプロダクト開発に関わってきて 2022年現在こうしたほうが良いと考えているベストプラクティスです。 科学的な分析等に基づくわけではない経験則であるため、今後も随時見直すことがありますし、 ここに書いてあることが常に正しいわけでもあらゆるソフトウェア開発に適するわけでもありません。 しかしながら、実務経験が豊富で、モダンな技術スタックに明るいエンジニアの経験則は一定の 役に立つのではないかと考えて記します。 技術文書とは ここでは、ソフトウェア開発で技術者が書くべき文書ということにします。 ソフトウェアエンジニアにも役割がいろいろあり、アーキテクトと independent contributor では書く文書が違うということはあるでしょうけれど、ここではごっちゃにします。
オンラインドキュメントと日本語全文検索
自社では Sphinx というドキュメントツールを利用しているのですが、残念ながらこれに付属している検索機能の日本語検索はかなり厳しいです。また残念ながら Sphinx 開発側も検索周りを改善するという予定は直近ではないようです。 そして検索というのはとても難しい技術なため自分のような素人では導入して「普通に期待する動作」をさせるまでの距離はとても遠いです。 ただ、なんとかして日本語全文検索を実現したいという思いはここ10 年くらいずっと思っていました。これは自社の Sphinx テーマを作ってくれている社員ともよく話をしていたのですが、どうしてもリソースをつぎ込めずにいました。 まとめ日本語検索に対応している Meilisearch を採用したドキュメントスクレイパーの実行は GItHub Actions (Self-hosted Runner) を採用した自社 Sphinx テーマの検
Diagram as Code
Diagram as Code6 different ways to turn code into beautiful architecture diagrams
アジャイルとは？LINEアジャイルコーチ 横道さんがわかりやすく解説！ | FLEXY（フレキシー）
FLEXY編集部の麻衣子お姉さんが、現場の最前線で活躍するエンジニアへ会いに行くこの企画。 「聞いたことあるけど良く分からない」「ざっくりと教えて」という非エンジニアならではの問いに答えてもらいます。技術書やWebで調べてもいまいち難しくて理解できないあんな技術やこんな技術。プロに優しく教えてもらいましょう。 今回のテーマは「アジャイル」。麻衣子姉さんもアジャイルという単語は聞いたことがあるものの、なぜ巷で流行っているのか、そもそもスクラムとの違いが何なのかは知らない様子。LINEの横道稔さんに伺いました。 アジャイルの基本をわかりやすく教えて！ 麻衣子：エンジニアの方がよく口にする「アジャイル」って何ですか……？「ウォーターフォール」との違いはなんでしょうか？ 横道：まず初めに、ウォーターフォールとアジャイルは対となる概念ではないということからお話させて下さい。 麻衣子：対比で語られるこ
障害報告書を書こう！ - Qiita
担当しているITサービスなどに何かしらのインシデントや障害が発生した時に、対処後のアクションとして報告書を提出して事象の内容を報告（レポート）する場合がある。 提出先は会社の偉い人だったりクライアントだったり。場合によってはユーザー向けに発表したり。事の顛末を報告して「今後同様のことを起こさないように努力します、ごめんなさい」をするのだ。どのように再発防止の努力するのかを書くものでもある。 主にクライアント向けのビジネス内容ではあるが、自分が使っているテンプレパターンを共有するので参考にしてもらえればと思う。1 全般的なポイント 心得のようなもの。次の点は留意してて欲しい。 淡々と冷静な説明をこころがける 当然のことながら事実は脚色しない。無駄な修飾も要らない。客観的な事実を簡潔に述べる。 例： ❌「一生懸命頑張って対応したが…」 ❌「寝ないで対応したが…」 ❌「本当の原因は…」 できるだ
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
テクニカルライティングの基本 2023年版
技術をわかりやすく伝えるためテクニカルライティング
テクニカルライティングの基本
