自分も含めて社内に詳しい人がいない領域のコードをいじることってあるよね。特に歴史の長いサービスだと当時触っていた人が誰もいないとか。仮にいたとしても1年くらい触ってないとほとんど忘れてしまって知らないのと同じような状態になっていたりする。 自分もそういうことが何度もあって、雑にスタンスややってることをまとめておこうと思う。 前提のスタンス 「これを倒したら俺がこの領域で一番詳しい最強になるんや」という気持ちを持ってる 詳しい人がいない状態で属人化とか気にしても仕方ない。まずは自分が詳しくなってから考えるでよい 自分用メモを作る キャッチアップしたことを書き残していく。ドキュメントじゃなくてSlackに垂れ流すでもいい 過去のドキュメント・やりとりを探す 全体像を把握できるドキュメントがないかを探すのを最初にやってる ここは近道はない。とにかく全部集めて全部読む気持ちで臨む Google D

Launchable, Inc.のソフトウェアエンジニアであるこんぼい氏は、ドキュメントを大事にしている理由と、具体的にどのようなドキュメントを運用しているのか、また、ドキュメント文化醸造のための取り組みについて紹介しました。全2回。前回はこちらから。 運用ドキュメント1　Project Proposal こんぼい氏：ここからがメインパートというか、どんなドキュメントを運用しているのかを紹介していければなと思います。 いろいろなドキュメントがあるんですが、今回は4つ例を持ってきました。1つ目がProject Proposal、2つ目がDACI（Driver, Approver, Contributors, Informed）、Postmortem、CS Investigation Logというかたちで持ってきました。 まず1つ目がProject Proposalですね。読んで字のごとくじゃ

Launchable, Inc.のソフトウェアエンジニアであるこんぼい氏は、ドキュメントを大事にしている理由と、具体的にどのようなドキュメントを運用しているのか、また、ドキュメント文化醸造のための取り組みについて紹介しました。全2回。 こんぼい氏の自己紹介 こんぼい氏：よろしくお願いします。「非同期な開発体制を支えるドキュメント文化」ということで発表します。 まず自己紹介をします。矢吹遼介と申します。Launchableという会社でソフトウェアエンジニアをやっています。インターネット上ではゴリラのアイコンで「Konboi」というIDでやっています。よろしくお願いします。 Launchableについて はじめにLaunchableについて軽く紹介させてください。USに本社があって、Jenkinsの作者の川口さん（川口耕介氏）がSun（Sun Microsystems）の時の同僚のHarpre

組織には構造化されたデータベースやきれいにフォーマットされたCSVのほか、何気なく書いたメールから複雑な技術マニュアルまでさまざまな形式のデータが大量に保存されています。検索拡張生成(RAG)は大規模言語モデル(LLM)を使用して全てのデータから適切な情報を引き出すための技術ですが、RAGを使用する際にデータの取り込みと前処理をどのように行うと効率的なのかを、RAG向けデータ前処理サービスを展開するUnstructuredが解説しました。 Understanding What Matters for LLM Ingestion and Preprocessing – Unstructured https://unstructured.io/blog/understanding-what-matters-for-llm-ingestion-and-preprocessing LLMを最大限に

はじめに 📘 この記事は ラクス Advent Calendar 2023 の7日目の記事になります。 要件定義から基本設計、さらに実装や保守運用に至るまでの一貫した経験を何度か積んできましたが、毎回 「要件定義って具体的に何の項目が必要だっけ？」 「基本設計との違いって何だったっけ？」 「基本設計と詳細設計の区別って？」 といった疑問が頭をよぎってきました。 そんなわけで、これまでの経験を振り返りつつ、開発プロセスについて１からまとめていくことで頭の中の大掃除を行なっていきたいと思います🧹 この記事の対象者 🎯 開発プロセスについて学びたい方 要件定義の基本を学びたい人 要件定義と基本設計の違いがわからない人 一緒に開発プロセスについて復習したい方 前提 記事中の一部（特に要件定義や基本設計、詳細設計のサンプル）を自動生成で作成してます。一貫性の無い内容があるかも知れませんが、あく

ParisWeb 2013: Learning to Love: Crash Course in Emotional UX Design

垂直スケーラビリティと効果的なテストによる金融取引システムのパフォーマンスと効率の最大化 Peter Lawrey氏はJavaチャンピオンであり、Chronicle SoftwareのCEOとして、開発者を鼓舞してソリューションのクラフトマンシップを高めることに情熱を注いでいる。経験豊富なソフトウェアエンジニアとして、Lawrey氏はソフトウェア開発プロセスにおけるシンプルさ、パフォーマンス、創造性、革新性を奨励することに努めている。

サバイバルTypeScriptは有志で執筆を進めているTypeScriptのOSSドキュメントです。 今回、サバイバルTypeScriptのドキュメントをベースにTypeScriptに関する質問に答えてくれるGPTsを作成・公開しました✨ この記事ではGPTs公開の背景や作成手順、現状の課題などをまとめています。 GPTs公開の背景 LLMによるドキュメント検索は近い将来（既に？）一般的になると思い、サバイバルTypeScriptでも実験的にチャットボットでの情報アクセスを作成・公開しました。 ドキュメントの情報アクセスの課題 ドキュメントが多くなると、目次やサイトマップ、サイト内検索だけでは必要な情報にアクセスするのが困難になる。 チャットボットのメリット 雑な質問でも意図を汲んで、知りたい情報にアクセスしやすい 内容を要約して説明してくれるので、手軽に情報にアクセスできる 回答の信頼性

Googleでの「Design Docs」とは 2007年の Google Developer Day Tokyo での鵜飼氏のプレゼンによると「Google で必ず書くことになっているドキュメント」であり、「プロジェクト立ち上げ時の 1～2週間をかけて書く」ものです。 今回は Google のソフトウェアエンジニアである @cramforce 氏が自身のブログで「Googleでの Design Docs」について解説している記事を公開されていたため、氏の許可を得て翻訳しています。 原文： www.industrialempathy.com 関連書籍： Googleのソフトウェアエンジニアリング ―持続可能なプログラミングを支える技術、文化、プロセス オライリージャパンAmazon 読了目安：11分 (目次) デザインドキュメント の解剖学 文脈と範囲 目標と非目標 実際のデザイン システ

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

git-schemlexとddl-makerを使ったDB migrationの紹介 / git-schemalex and ddl-maker migration #golangtokyo

初めに 吉澤準特さんの「図解作成の基本」という本を読む機会があり、 自分自身の理解を深める意味で今回は執筆させていただきます。 参画しているプロジェクト先ではドキュメント作成を行うことが多くあるため本で学んだことを、整理して今後の資料作成に生かせればと思います。 図解の目的とは 文章だけでは伝わりにくいのものを図を用いて、 相手に理解やイメージをしやすく説明するためのものです。 図解は以下に記載の３つの「見せ方」を用いることで 相手にわかりやすく伝えることができます。 今回は３つの見せ方について簡単にまとめたいと思います。 ３つの見せ方 １．フォーム：線の使用を控える ２．カラー：使う色を絞る ３．ポジション：図の位置を整える １．フォーム：線の使用を控える 線で組まれた図形は、図の数が増えるに従い 線の数も増えてしまいます。 線の数が増えることで、文字より線自体が目立ってしまうこともあり

はじめに 皆さんは、『公式ドキュメントを読んだほうがいいよ』とよく耳にしませんか？ そこで、『よし読むぞ！』と思っても、なかなかうまくいきませんよね💦 （そういう方々がこの記事を見に来てくれると思っている👀） 私も、公式ドキュメントを読むのが苦手で、まず最初に、Qiitaなどの技術系ブログに頼ってしまいますw そこで、なぜ自分が公式ドキュメントに苦手意識があり、どうしたらその抵抗をなくせるのかを考えたので、記録として記事にしたいと思います！🙆 ちなみに、公式ドキュメントとの思い出は、1年前ぐらいにDockerの公式ドキュメントで何が書いてあるか理解できず、15分くらいで読むことを諦めましたw ※自分がこの記事を通して公式ドキュメントが読めるようになるために努力した記事なので、公式ドキュメントを批判した記事ではないです！ 対象読者 公式ドキュメントを読むのが苦手な若手エンジニア 😅公

エンジニアリングユニットの酒井といいます。 昨年の9月に入社し、Anewsの開発に従事しつつ時々SREっぽいこともしています。 今回は、自分が入社当初から改善したいなぁと考えていたAnewsのドキュメントについて、これまでやってきた取り組みについてお話しできればと思います。 取り組みを始めたきっかけそもそも自分は組織開発において、ドキュメントが重要だという認識がありました。それはこれまでの経験則によるところもありますし、『Googleのソフトウェアエンジニアリング』中で以下のような言及があり、重要性を再認識したというのもあります。 10.2 何故ドキュメンテーションが必要なのか p220: ドキュメンテーションは長期的に見ると決定的に重要であり、決定的に重要なコードにとっては特に、組織がスケールするのに伴い途方もない恩恵をもたらす。 テストを書くことは普通になりつつありますが、ドキュメント

はじめに 本記事はアウトプットの心構えのカレンダー | Advent Calendar 2023の4日目の記事です こんにちは！！@Sicut_studyです！ 私はアウトプットの大切さを日頃から発信しており、実際にQiitaにたくさんの記事を投稿しています そんな中で、自分なりに高速に記事としてアウトプットできるフレームワークを使っているのでそのフレームワークについて紹介していきます アウトプットの大切さ まず言っておきたいのはアウトプットは質より量です 量が増えるとだんだんと質もあがります 私は駆け出しのエンジニアの方に普段から「100本記事を書けば人生変わる」と言っています。 そもそも世の中に100本記事を書いたことのある経験をしたことがある人はごく僅かです そんなごく僅かな人になれれば絶対人生が変わります。 多くの人ができないことをやり遂げられる。しかも記事という形で目に実力が見え

はじめに こんにちは、LLM Advent Calendar 2023 4日目の記事を担当する_mkazutakaです。よろしくお願いします。 LLM Advent CalendarといってもRAGの話になりますが、ご容赦ください。 企業独自のデータを使ってLLMからの出力を制御する際には、検索拡張生成(いわゆるRAG)が使われます。 RAGの実装方法としては、「PDFからドキュメント情報を読み取り検索エンジンに保存」「ユーザの入力する質問文から関連するドキュメントを検索エンジンから取得」「取得したものをコンテキストとしてプロンプトに含める」という流れが一般的だと思います。 この際、RAGの課題の一つでもあるのですが、検索結果から取得するドキュメントのサイズ(いわゆるチャンクサイズ)をどれぐらいのものにするかというものがあります。チャンクサイズが小さすぎるとLLMは関連するコンテキストから

はじめにTIG真野です。 秋のブログ週間2023 の3本目は、設計ドキュメントをGit管理して腐らせないようにがんばってみた話をします。 前段として6年前、「我々はいかにシステム開発におけるドキュメント腐る問題と戦えば良いのか」という記事を書いたのですが、その後の試行錯誤はどこにも残していないことに気づきました。普段のフューチャー技術ブログですとちょっと引け目を感じるテーマですが、秋の夜長を楽しむため読み物成分を多めに書くというテーマのこのブログリレーにピッタリな気がするため、この機会をお借りします。 ドキュメントも色々な種別があるかと思いますが、この記事では設計ドキュメントを指すことにします。設計ドキュメントは開発メンバーが参照するもので、ステークホルダーへの説明資料に引用して使うことはあれど、主目的は異なるという前提です。Design Docの場合もありますし、システム構成図、ERD、

ROUTE06では、GitLab Handbook*1を参考に、全社に関係する情報をハンドブックとして社内に公開しています。ハンドブックは2023年8月時点で383ページ*2あり、50人前後の組織規模の会社としては文章化に積極的なことが現れている数字だと思っています。 また、ハンドブックとは別に、プロジェクトごとのレポジトリでは技術選定や設計方針をADR*3で残していたり、参加したセミナーのレポートをGitHub Discussionsに書いていることからも、ROUTE06で働く人は文章を書くことが習慣になっていると感じます。 そんな中、ある日社内のSlackに一つの問いが投げかけられました。 ドキュメント文化というのは、たとえばマニュアルに書いてないから分からなかった・故になんらかの失敗が発生した場合、マニュアルに書いていなかったことが悪いみたいな考え方になるのでしょうか 社内のSlac

「private 関数にはテストを書かない」というのが多数派だと思う。だが昨日、仕事で In-source testing を書いていたらふと private 関数にテストを書きたくなった。そこで、In-source testingができる環境下でもprivate 関数にテストを書くべきかを X で聞いてみたら何か盛り上がっていた。 (In-source Testing: https://vitest.dev/guide/in-source.html) 反応を見る限り、やはり「private 関数にはテストを書かない」の方が主流だった。Kent Beck先生の http://shoulditestprivatemethods.com を紹介するツイートにもそういった反応が寄せられていた。（ぶんぶんさん、教えてくれてありがとうございます。） （このサイト面白すぎますよね・・・） 自分の立場を