社内ドキュメントはなぜ更新されないのか？情報の鮮度を最小限の運用負荷で維持する「イミュータブルドキュメントモデル」のススメ - KAKEHASHI Tech Blog
はじめに こんにちは。カケハシの各プロダクトを支えるプラットフォームシステムの開発チームでテックリードを担当している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（株式会社エーピーコミュニケーションズ）さんが「カプセルト
2004年1月2月に放送された番組だが、先日の11月8日9日の深夜に再放送された。今はNHKプラスの配信で一週間見ることができる。 選「ドキュメント・エルサレム」(前編) - NHKスペシャル - NHK https://www.nhk.jp/p/special/ts/2NY2QQLPM3/episode/te/MV8W36W6XX/ （追記：後編のURLもつけときます。選「ドキュメント・エルサレム」(後編) - NHKスペシャル - NHK https://www.nhk.jp/p/special/ts/2NY2QQLPM3/episode/te/XZR9W44JV3/ ） 最近作られた「映像の世紀」とかのイスラエルドキュメンタリーやパレスチナ紛争の解説番組なんかと比べてよっぽど中身があった。 イスラエルの穏健派政治家たちが和平を結ぼうとするたびに、虐殺者シャロン率いるリクードなどの大イ
安野モヨコが夫・庵野秀明のドキュメントを見たら「カメラの前でほとんど心を開かないままに終わったのでひっくり返った」。監督の＜断固として＞との姿勢を生き方の指針に 還暦不行届｜話題｜婦人公論.jp
漫画『ハッピー・マニア』で人気を博し、その後の作品『シュガシュガルーン』では第29回講談社漫画賞を受賞するなど、数々の名作を生み出している、漫画家・安野モヨコさん。そして、安野さんのパートナーはアニメ『新世紀エヴァンゲリオン』の監督・庵野秀明さん。このクリエイティブなご夫婦は一体どんな生活を送っているのでしょうか。安野さんは、「監督は眠っている時の姿が浜辺に打ち上げられた棒みたい」と言っていて――。 集中力 監督は眠っている時の姿が変わっていて 浜辺に打ち上げられた棒みたいに一本になって寝ている。 体の中にある本体が抜け出して、その際入れ物である肉体を ぽいと投げ出して出かけてった、というような感じがする。 なんでそんなふうに感じるかというと 普段から監督の動きがそんな様子だからだ。
Jira SoftwareやTrelloなどを中心としたPMが経験してきたプロダクト管理ツールの失敗や改善を語る「本当に使いこなせてる？プロダクト管理ツールの失敗&改善PMトーク【開発PM勉強会 vol.20】」。ここで株式会社ビズリーチの菊池氏が登壇。ドキュメント管理とプロダクトバックログの失敗から学ぶツール運用のコツについて紹介します。 菊池氏の自己紹介 菊池信太郎氏（以下、菊池）：ビズリーチの菊池から、10分枠で話をします。今日のテーマは「失敗から学ぶドキュメントとチケット運用のコツ」ということで、今まで経験したところで「こういうアンチパターンがあったよ」「こういう改善をしたよ」というようなところをお話しできればと思っています。 自己紹介を軽くすると、（私は）2018年からビズリーチで働いています。ビズリーチサービスを作っていて、プラットフォーム開発部の部長をしています。また、201
はじめにTIG真野です。 秋のブログ週間2023 の3本目は、設計ドキュメントをGit管理して腐らせないようにがんばってみた話をします。 前段として6年前、「我々はいかにシステム開発におけるドキュメント腐る問題と戦えば良いのか」という記事を書いたのですが、その後の試行錯誤はどこにも残していないことに気づきました。普段のフューチャー技術ブログですとちょっと引け目を感じるテーマですが、秋の夜長を楽しむため読み物成分を多めに書くというテーマのこのブログリレーにピッタリな気がするため、この機会をお借りします。 ドキュメントも色々な種別があるかと思いますが、この記事では設計ドキュメントを指すことにします。設計ドキュメントは開発メンバーが参照するもので、ステークホルダーへの説明資料に引用して使うことはあれど、主目的は異なるという前提です。Design Docの場合もありますし、システム構成図、ERD、
「すげえ。パクってやがる。ここまでクズども、見たことねえ」小説落選、青葉被告が徐々に過激行動へ 大宮駅前無差別殺人事件計画を初めて語る【ドキュメント京アニ裁判⑦被告人質問】 | TBS NEWS DIG
「すげえ。パクってやがる。ここまでクズども、見たことねえ」小説落選、青葉被告が徐々に過激行動へ 大宮駅前無差別殺人事件計画を初めて語る【ドキュメント京アニ裁判⑦被告人質問】
選「ドキュメント・エルサレム」(前編) - NHKスペシャル
ユダヤ教、キリスト教、イスラム教の三つの宗教の聖地、エルサレム。３０００年にわたり様々な衝突の震源地となってきた。世界を揺るがしている紛争がどのように始まったのかを、二組の父子と貴重な記録映像で検証する。２回シリーズの前編。
シンプルに自己アピールで勝負 ソフトウェアエンジニアのコニー・リー（33）は昨年、恋人と別れた後、ふたたびマッチングアプリを使うようになった。しかし、そこで出会った男性の多くはカジュアルな関係を求めているようだったので、彼女は違う方法を試してみることにした。 それは、記事1本分ほどもある長い履歴書のようなプロフィールを書くことだった。デート相手を探すために、レジュメのような長い自己紹介文を他人がオンラインで公開しているのを見たことがあったのだ。
エンジニアに英語力が必要な本当の理由を知ってますか？「英語でしか存在しないドキュメントを読むため？」「違いますね」→許したくない事案がココにある
米村歩@日本一残業の少ないIT企業社長 @yonemura2006 エンジニアが英語力が必要な本当の理由を知ってますか？英語でしか存在しないドキュメントを読むため？違いますね。ずばり、センスの欠片も感じられない変数名やメソッド名を付けないようにするためですよ。あれやるやつマジ許さん。 2024-05-23 18:16:07
マイクロソフト、GPT-4に任意のドキュメントなどを読み込ませて回答してもらえる「Azure OpenAI Service On Your Data」が正式サービスに
マイクロソフトは、GPT-35-TurboもしくはGPT-4に任意のデータソースを指定することでそのデータの内容を読み込み、質問に対して内容を基に回答できるようになる新機能「Azure OpenAI On Your Data」が正式サービスとなったことを発表しました。 例えば、社内規約や社内マニュアルなどを読み込ませると、「PCの修理を申し込むための社内手続きは？」といった、汎用の知識だけしか持たない従来のGPTでは答えられない質問にも回答できるようになります。 任意のドキュメントを読み込ませるための支援ツール「Azure AI Studio」には、Azure OpenAI On Your DataでカスタマイズしたAIを、チャットボットとして公開する機能も備わっています。 カスタマイズしたチャットAIのサービスを、社内や社外に簡単に公開できるようになります。 Azure OpenAI S
本記事の要約 ドキュメントを書かない事は、企業やチームの「負債」になる ドキュメントを書かない事は、自身の学びや振り返りの「機会損失」になる そういう文化が根付く前に、負の連鎖を断ち切ろう！ はじめに 世の中のプロジェクトには、ドキュメントが足りていない、と感じています。 でも残念な事に、ドキュメントをどうしても書きたい人は「ほとんどいない」と思います。 その一方で「ドキュメントを書いた方が良い」という事は、 何となく分かっている人も多いと思います。 やりたくない事をやらなければならないのは、嫌ですよね。 そんな気持ちは分かりますが、これを機に一度改めてみませんか。 何故なら、ドキュメントを書かない事はチームに「負債」を生むからです。 勤め人ならば少なからず一度でも、体験した事があると思います。 「どうして必要な過去の資料が無いんだ」って。 あるはずの歴史の一端がソースコードからしか分から
設計ドキュメント腐る問題、 Git管理で運用してみた 本当のところ 2023.12.5 真野隼記 ドキュメント管理を制する 陳腐化を防ぐための実践事例 Lunch LT
はじめに Domain Name System（DNS）はインターネットサービスを使用する上で欠かせない基幹サービスであり、DNSが関連するセキュリティインシデントへの対処は、健全なインターネットを維持するために重要です。本ブログでは、JPCERT/CCもメンバーとして参加しているFIRSTのDNS Abuse SIGが、2023年2月に公開したDNS Abuse Techniques Matrixについて、その日本語版をJPCERT/CCが主体となり作成および公開したので紹介します。 2023年2月、FIRSTのDNS Abuse SIGが公開したDNS Abuse Techniques Matrix - DNS Abuse Techniques Matrix https://www.first.org/global/sigs/dns/DNS-Abuse-Techniques-Matri
画像・PDF・TXT・メールなどの中身を読み取って検索できるようにするオープンソースのドキュメント整理ツール「Teedy」レビュー
Teedyはさまざまな種類のファイルの中身を読み取って検索できる状態にしてくれるドキュメント整理ツールです。受信したメールを自動で取り込む設定もできるとのことなので、実際にセルフホストして使い勝手を確かめてみました。 sismics/docs: Lightweight document management system packed with all the features you can expect from big expensive solutions https://github.com/sismics/docs TeedyのインストールにDockerを利用するので、下記のリンクから自分の環境に合った方法でDockerをインストールします。 Install Docker Engine | Docker Documentation https://docs.docker.com
［速報］GitHub、組織のコードやドキュメントを学習しカスタマイズやファインチューニングが可能な「Copilot Enterprise」発表。GitHub Universe 2023
［速報］GitHub、組織のコードやドキュメントを学習しカスタマイズやファインチューニングが可能な「Copilot Enterprise」発表。GitHub Universe 2023 GitHubの年次イベント「GitHub Universe 2023」が米サンフランシスコで開幕しました。 1日目の基調講演で、Copilotが組織のコードやドキュメントを学習することで、カスタマイズやファインチューニングが可能になる「GitHub Enterprise」が発表されました。 Copilot Enterpriseは、外部に公開されていない組織内のコードやドキュメント、プルリクエストなどを追加でCopilotに学習させることで、組織内のコードベースに基づいたCopilotによるコードの生成や、Copilot Chatでの質問に対する回答が可能になるというものです。 さらに言語モデルそのものを組織
git-schemlexとddl-makerを使ったDB migrationの紹介 / git-schemalex and ddl-maker migration #golangtokyo
はじめまして。損害保険ジャパン株式会社 DX推進部の眞方です。普段はリードエンジニアとして、新しいサービスのアーキテクチャ検討からローンチまでの作業や、新規技術を用いたアプリのプロトタイプ実装などを行なっています。 弊社では、LLM（Large Language Models）を活用したアプリケーションの開発を積極的に検討し、既に社内でいくつかのプロトタイプをローンチしています。 本記事では、その最も一般的？なユースケースの一つとも言えるRAG（Retrieval Augmented Generative）の構築において、ドキュメント検索精度の向上にどのように取り組んだ内容の概要を紹介させていただきます。実際の詳細な手法および結果については、別記事（実践編）で解説予定です。 はじめに RAGとは？ この記事を読まれている方の中にはご存知の方も多いでしょうが、RAGとはRetrieval A
困った時はドキュメント、どうもかわしんです。最近、諸事情で SQLite のドキュメントを読んでいます。 前回の記事 で紹介した通り SQLite を Rust で再実装しています。おかげさまで 300 を超える Github Star もいただき嬉しいです。 github.com SQLite は全ての仕様が ドキュメント にまとめられているので、そのドキュメントと本家の実装を読み比べながら実装しています。 SQLite を再実装する上で特に以下のドキュメントは役にたちます。これらだけで最小限の SQLite の実装は作れると思います。 Overview Documents > About SQLite いかに SQLite がすごいかを自慢しているドキュメント。使おうとしている人には安心を、再実装しようとする人には絶望を与えてくれます。 Programming Interfaces >
ドキュメント執筆にもGit、ビルド、テストで再利用性や整合性を実現する「Writerside」、JetBrainsがプレビューリリース
Kotlinなどの開発元として知られるJetBrainsは、テクニカルドキュメントのための一連のツールを統合したドキュメントオーサリングツール「Writerside」のプレビューリリースを発表しました。 ソフトウェア開発においては、テキストで記述されたソースコードをGitでバージョン管理し、ビルドによって複数のソースコードを1つのアプリケーションへとまとめ上げ、コンパイルし、テストをして本番環境へのデプロイによりアプリケーションを公開します。 そしてこのプロセス全体を、さまざまな機能を備えたツールチェンを用いて自動化することで、ソフトウェア開発の効率を高めています。 一方で、例えばアプリケーションのチュートリアル、SDKやAPIのリファレンスドキュメントなどのドキュメントの制作過程においては、複数のファイルをフォルダにまとめ、手作業で目次のページとリンクさせることや、ソースコードのサンプル
APIの開発は複雑でコストがかかる可能性があり、頻繁に更新されることからドキュメントを整備するのも難しい。APIの設計、開発、ドキュメントの整備、管理にまつわる課題と効率さの問題に対処するアプローチが、RESTful API Modeling Language（RAML：RESTful APIモデリング言語）だ。 RAMLコードを使えば、開発者はAPIの動作を説明する仕様を策定してからそのAPIをデプロイするまでのAPIライフサイクルを管理することができる。 RAMLとは RAMLは、RESTful APIを記述することを目的とするオープンソースの記述言語だ。2013年、米国のIT自動化および統合ベンダーであるMuleSoftを中心とする数社の企業によって作成されたRAMLはAPIの開発に大きな役割を果たしてきた。2018年、MuleSoftはSalesforceによって買収され、RAML
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
「ドキュメントの書き方」を体系的に学んだことがないエンジニアへ 書籍『エンジニアのためのドキュメントライティング』の概要
NHKスペシャル「ドキュメント エルサレム（前後編）」がすごかった
破綻したドキュメント管理、増え過ぎたプロダクトバックログ… 「Jira」「Confluence」などの活用失敗から学ぶツール運用のコツ
設計ドキュメント腐る問題、Git管理で運用してみた結果 | フューチャー技術ブログ
「マッチングアプリ」に疲れて「Googleドキュメント」に移行する人々が増加中 | もうスワイプする必要はない
ドキュメントを書かないことは「負債を生む」ということ - Qiita
20231206_設計ドキュメント腐る問題、Git管理で運用してみた本当のところ
DNSの不正使用手法をまとめた技術ドキュメントの公開 - JPCERT/CC Eyes
非同期開発体制を支えるドキュメント文化 / YAPC::Hiroshima 2024
RAGにおけるドキュメント検索精度向上について(概要編)
SQLite を再実装する時に役にたつドキュメント - kawasin73のブログ
RESTful APIの設計、開発、ドキュメント管理を手助けする「RAML」とは