背景 開発チームが抱えるよくある課題として システムが変化する一方でドキュメントは更新されず腐る メンバーの流入出によって口伝でかろうじて継承された知見も失われる 検索性が良くないと過去のドキュメントが気づかれず、同じような内容のドキュメントが新規量産される 後から参加したメンバーはどちらが正のドキュメントか分からず混乱する といったことが良くあります。 解決方法としては以下のように、GitHub＆ルールベースで管理するといった例があります。 future-architect.github.io また組織・システムが大きくなってくると認知負荷を低減するためにドメインで区切るような形でチームの分割が始まりますが、 異なるチームによってシステムが管理され、システムの依存関係を全て知っている人がいなくなる CxOレイヤが大規模イベント前に現状を把握したいときに都度時間がかかってしまう チームごと

宿泊開発チームでエンジニアをしている @kosuke1012 です。チームで ADR を書き始めて1年くらい経ったので、その感想を書いてみたいと思います。 この記事は 一休.comのカレンダー | Advent Calendar 2023 - Qiita の13日目の記事です。 ADRとは アーキテクチャ・ディシジョン・レコードの略で、アーキテクチャに関する意思決定を軽量なテキストドキュメントで記録していくものです。 出典はこちらで、 Documenting Architecture Decisions わかりやすい和訳は以下の記事が、 アーキテクチャ決定レコードの概要  |  Cloud アーキテクチャ センター  |  Google Cloud アーキテクチャ・デシジョン・レコードの勧め | 豆蔵デベロッパーサイト アーキテクチャの「なぜ？」を記録する！ADRってなんぞや？ #設計 -

はじめに こんにちは。カケハシの各プロダクトを支えるプラットフォームシステムの開発チームでテックリードを担当しているkosui(@kosui_me)です。 プロダクト開発の世界では、明瞭な社内向けドキュメントを書くための方法が数多く提案されてきました。読者の中には、製品要求を明瞭にするためにPRD (Product Requirements Document、製品要求仕様書) を書き、プロジェクトの背景から全体の設計やその代案について明瞭にするためにDesign Docsを書き、アーキテクチャに関する意思決定の記録を明瞭にするためにADR(Architecture Decision Record) を書いてきた方も数多くいらっしゃると思います。 しかし、どんな素晴らしいドキュメントも、何故か更新されなくなります。新メンバーへのオンボーディングのためにインフラ構成図を検索したあなたが見つけた

インフラエンジニア向けの書籍を取り上げ、著者と出会い、楽しく本を知り、仲間を作る場所である「インフラエンジニアBooks」。ここで、『ユーザーの問題解決とプロダクトの成功を導く　エンジニアのためのドキュメントライティング』の翻訳を担当した岩瀬氏が登壇。まずは、本書籍の概要について話します。 本セッションの対象者と、セッションのゴール 岩瀬義昌氏：ご紹介いただきました、岩瀬と申します。よろしくお願いします。『ユーザーの問題解決とプロダクトの成功を導く　エンジニアのためのドキュメントライティング』は、もともと『Docs for Developers: An Engineer’s Field Guide to Technical Writing』という洋書だったんですが、その翻訳をして、今回この機会をいただいています。 余談ですが、APC（株式会社エーピーコミュニケーションズ）さんが「カプセルト

2023年7月27日「Developers Summit 2023 Summer」にて 「日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード」というタイトルで「ADR」について発表した資料です

本記事の内容 ドキュメント、書いてますか？ こんにちは。データエンジニアの加藤です。社内データプロダクトである Knile1 と Crois2 の開発・運用や、社内に複数あるデータプロダクトの統合や連携などを見据えたリアーキテクチャを担当しています。 唐突ですが、チーム開発をしている皆様は、日常業務でドキュメントを書いていますか？ 4 月の新卒社員の配属や組織再編・異動など、人や組織が大きく入れ替わる時期を終え、以下のような課題を再認識したチームも多いのではないでしょうか。 オンボーディングのドキュメントが整っていない 現状のアーキテクチャ図が整備されていない プロダクトのデバッグ対応が言語化されていない 自チームでもこういった問題は常に挙がっていましたが、ドキュメンテーション改善はなかなかされない状況が続いていました。 リモートワークが中心の業務では特に、暗黙知をきちんと言語化し、属人性

大手ITスタイルガイドがベースGoogleやMicrosoftなど大手IT企業の英語スタイルガイドの基準がベース。一般的な英語表記から外れません。

みなさん、コードを書く前に設計書を書きますか？ 書くか書かないかは人それぞれだと思いますが、「設計」というプロセス自体は意識的であれ無意識的であれエンジニアであれば全員やっていることだと思います。 今回は設計プロセスの改善という文脈で私たちがDesign Docという仕組みを導入したことについて共有しようと思います。もし同じような状況を経験している人がいたら参考になれば幸いです。 導入の背景まずは導入するに至った状況からお話します。 私たちのサービスは、利用していただくユーザーの数が増加しています。それに伴って品質のハードルも上がってきました。サービスに障害が発生するとユーザーさんに大きな損害を出してしまうことになるからです。そこで今まで以上に安全にサービスを開発できる仕組みづくりが必要になりました。ですが、実現のためには大きく2つの課題がありました。 課題1. 開発スピードが徐々に鈍化し

最近知った興味深いPodcast e34.fm で紹介されていたので興味を持って読んでみた本「Docs for Developers: An Engineer’s Field Guide to Technical Writing」に関するメモ。 2023/3追記：翻訳されたようだ。ユーザーの問題解決とプロダクトの成功を導く　エンジニアのためのドキュメントライティング e34.fmwww.oreilly.com この記事の目次 「Docs for Developers」はどんな本なのか 全般的な感想 各章に関する覚え書き Front Matter Chap 1. Understanding your audience Chap 2. Planning your documentation Chap 3. Drafting documentation Chap 4. Editing docum

こんにちは。テクノロジー本部のyoshikawaです。好きなW3C Recommendation は RDF 1.1 Concepts and Abstract Syntax です。 会議やチャットでのやり取りの決定事項・議事録、アプリケーションや機能の設計書・仕様書、READMEなどなど... LIFULLの開発現場においては、ソースコード以外にもこのように様々な文書の管理・蓄積(=ドキュメンテーション)を実施しています。 多くの開発者・メンバーがドキュメンテーションの重要性やその恩恵は理解はしているものの、なかなかうまく情報の蓄積・管理ができない、 その結果、本質的ではない調査に時間を取られてしまいDeveloper Experienceが下落してしまう。 このような課題を抱えているプロジェクトやチームは世の開発現場において少なからず存在すると思います。 LIFULLの開発現場にもこの

ドキュメントツールのインストール(Windows) Macの場合の設定方法は、本項の後に記載 PowerShellの起動 各種ツールをインストールするため、PowerShellを管理者として実行 Windowsボタンを押下 powershell と入力 右クリックで管理者として実行 を選択します Chocolateyのインストール 本手順は前述で起動したPowerShellを利用 1.Chocolatey のサイトにアクセスし、インストールコマンドをクリップボードへコピー 2.前項でコピーしたコマンドをPowerShellにペーストして実行します Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServiceP

npm のちょっとしたオプションについては以下を参照。 Step.1 本体と最低限のルールをインストール 任意のフォルダを作成。 C:\workspaces\textlint_work cd C:\workspaces\textlint_work npm init -y npm install --save-dev textlint textlint-rule-preset-ja-spacing textlint-rule-preset-ja-technical-writing 上記で、textlint 本体 + プリセット2つをインストールする。 preset-ja-spacing preset-ja-technical-writing npx textlint --init で、.textlintrc が生成される。 Step.2 追加のルールをインストール 上を参考に入れてみる。 n

こんばんは。リモートワークを当たり前にしたい、石倉です。 いきなり本題ですが、仕事においてみなさん自身やみなさんの周囲で「言った方が早い」「直接話した方が早い」と思っている方はいますか？ 何を隠そう、僕もずっとそう思ってました。 もちろん議事録は大事なのはわかっているし、ドキュメントに残す、ツールに履歴を残す、タスクを見える化する、、、大事なのはわかっています。でも、ぶっちゃけめんどくさい。。 そして思ってました「言った方が早い」「直接話した方が早い」と。 ここ5年はずっとリモートワークで働いていますが、確かになかなかテキストで表現したり図で示せないことも多く、口頭でのコミュニケーションを行なった方が理解できることもあるし、早い場面はたくさんあります。 でもこれって本当に「早い」んでしょうか？ 確かにAさんと2人で話しているだけであれば直接話した方が早い、言った方が早いこともたくさんありま

多機能ノートツールの｢Notion｣が、じわじわと人気を集めている。全世界1000万人以上のユーザーがおり、すでに日本法人も始動している。 Notionを一言でいうなら｢何でもできるドキュメントツール｣だろう。メモやドキュメント、データベース、Wiki、タスク、プロジェクト管理からファイル管理まで。複数のクラウドツールに分散しがちな仕事に必要なあれこれを集約し、管理、共有できる。さらに、ドキュメントの一部をそのままWebページとして公開することも可能だ。 オンラインツールに感度の高い一部のスタートアップでは、すでにNotionを業務に取り入れて使い始めている。 ネットスーパーの垂直立ち上げサービスを提供する10X（テンエックス）社の事例から、｢業務で使うNotion｣の実例を見ていこう。

大学や大学院で論文の書き方を鍛え上げた人たちには遠く遠く及ばないが、僕の様なはぐれもの1でも最近は Amazon 社内で文書の質が高いと評価してもらえるまでにはなった。Software Engineer として、コードでのアウトプットはもちろん大事だけど、文書のアウトプット(およびそれによって得られた実際のアウトプット)は同じだけ重要である2。今回は自分が最近どういうところに気をつけて技術文書を書いているのか、ということについて数年後の自分が忘れてないことを確かめられる様にまとめておく。 そもそも文書とは？ 英語だと document。ここで指す(技術)文書とは、人間が読む文体で書かれた技術に関連する情報、といったものだ。具体的に言うと以下の様なものを想定している: 新しいプロジェクトの骨子を説明する資料 会議の叩き台となる 1 枚ペラ 本番環境に変更を加えるにあたっての包括的な情報や具体

サービシンクの名村が25年に渡るWeb制作のプロジェクトマネジメントで「テキストで情報を伝える」上で認識齟齬に至る点を洗い出した「誰がどう見てもそうとしか受け取れない文書術」のセミナースライドの2020年3月29日公開版です。 Web制作・システム開発に関わる人以外には事例等が分かりにくいかもしれませ…

OSC 2020 Tokyo/Spring でやる予定だったセミナーの資料です。 https://www.ospn.jp/osc2020-spring/modules/eguide/event.php?eid=44 残念ながらOSC東京春は今回は中止となってしまったのでとりあえず公開しておきます。

ドキュメント文化は健全な組織のスケールのために必要　組織の中でドキュメント/文章を残し活用していくことはとても重要だ。クオリティの高いドキュメントがあることで、組織に情報が流通し、透明性を確保できるようになる。情報を流通させるためにいちいち口頭の説明がいらないから、メンバーの数が増えた時でもスケールしやすくなる。過去の結論にアクセス可能になるので、議論を積み上げていき、意思決定のクオリティを高めることにもつながる。そもそも何かを読むということは何かを聞いて教わるよりも時間あたりの処理量が多いし、非同期に実施できる。良いドキュメントをアセットとして社内に蓄積していくことはスタートアップのみならず、ありとあらゆる組織が成長していく上でとても重要であると言える。 しかしその一方で、良質なドキュメント文化を徹底できている会社は多くないように見える。例えば、社内のドキュメントを蓄積させていく場所とし