情報の見つけやすさを追求する - 社内ドキュメンテーションの階層整理術 - KAKEHASHI Tech Blog
カケハシのプラットフォームチームでソフトウェアエンジニアをしているすてにゃん (id:stefafafan) です。今回はチームに配属されて数ヶ月の私が、いかにして社内ドキュメンテーションの階層構造を整理し、情報の検索性を向上させたかについてお話します。 はじめに この記事の想定読者 課題意識 メンバーへの共有と相談 社外事例の調査 esa の階層整理 第 1・第 2 階層の整理 ストック情報とフロー情報を意識した階層の整理 esa の機能をフル活用する 効果や今後について はじめに カケハシでは全社的にドキュメンテーションツールとして esa - 自律的なチームのための情報共有サービス を利用しています。それぞれのチームやプロダクトごとに階層を切ってドキュメントを書いています。 プラットフォームチームでは認証基盤などの社内プラットフォームシステムを開発しているため、自チームが運用する各種
組織が記憶喪失になるのをどうすれば ～ ryuzee技術顧問にきいてみた - NTT Communications Engineers' Blog
何か決定した事実は実装や規則の形で残っているものの、決定までの経緯をチームメンバーが覚えていない――。 この記事では、そうした組織が記憶喪失になることにどう対処していけばよいか、NTT Comの技術顧問である吉羽龍太郎 (@ryuzee) さんにふらっと相談してみたら一瞬で突破口が見つかった＆話に奥行きが出た話を共有します。 目次 目次 軽く自己紹介 事の発端 ryuzeeさんの油セール 実際に聞いてみた 新たなる概念：ADR ADRの実践：その1 何を書くか ADRの実践：その2 どこに書くか ADRの実践：その3 どう書くか 相談を受けて試しに書いてみたADR まとめ 軽く自己紹介 イノベーションセンターの小林 (@ppyv) です。 開発・検証用PCの開発に一段落つけた後、社会人学生としてたっぷり2年間学習を積んでいました。 いまはイノベーションセンターで働く社員のみなさんに、よりよ
初心者大学生が作った機械学習ライブラリがGitHubでスター数300を超えた話 - Qiita
この記事について この記事では、プログラミング初心者の大学生である(であった)私が試行錯誤しながらなんとかスター数300越えのOSSライブラリを作った過程をまとめたものです。ライブラリ自体はまだまだ発展中のためこの記事も適宜更新してく予定です。ライブラリ自体の詳細というよりも、自作OSSの認知度を上げで他の人に使ってもらうために有用そうな知見をまとめていこうと思います。 ライブラリの概要 今私が作っているのは、AIJackという、機械学習モデルがもつセキュリティ・プライバシー上の脆弱性についての各種攻撃・防御手法を実験するためのPythonツールです。既存のライブラリの多くは特定の種類の攻撃や防御に特化したものが多く、複数のタイプの攻撃・防御を組み合わせて実験するためにはいくつものライブラリを組み合わせる必要がありました。そこでAIJackでは、できる限り統一的なAPIで様々な攻撃・防御手
テキストから図が生成できるMermaidでAWS構成図をつくる - Qiita
はじめに テキストからダイアグラムの図が生成できるMermaidでAWS構成図をつくる方法を紹介します。 また、MermaidはGithubやQiitaなどのWebサービスやVSCodeやIntelliJなどのツール、コマンドやWebシステムでも使用できますので、良ければ下記の記事もご確認ください。 Mermaidのことはなんとなくわかったけど、AWSの構成図や配置図が描けないか考えていた人にも参考になれば幸いです。 AWSの構成図をつくる ・どんな感じの図ができるのか AWSの構成図を描くときにはAWS公式から提供されている[AWS Architecture Icons]というAWSのダイアグラムを書く際のアイコンセットを利用する機会が多いと思いますが、Mermaidでは残念ながらまだ使用できません。 そこで、アイコンの使用は諦めてAWSに関するグループやサービスについて、それっぽく見え
安野モヨコが夫・庵野秀明のドキュメントを見たら「カメラの前でほとんど心を開かないままに終わったのでひっくり返った」。監督の＜断固として＞との姿勢を生き方の指針に 還暦不行届｜話題｜婦人公論.jp
漫画『ハッピー・マニア』で人気を博し、その後の作品『シュガシュガルーン』では第29回講談社漫画賞を受賞するなど、数々の名作を生み出している、漫画家・安野モヨコさん。そして、安野さんのパートナーはアニメ『新世紀エヴァンゲリオン』の監督・庵野秀明さん。このクリエイティブなご夫婦は一体どんな生活を送っているのでしょうか。安野さんは、「監督は眠っている時の姿が浜辺に打ち上げられた棒みたい」と言っていて――。 集中力 監督は眠っている時の姿が変わっていて 浜辺に打ち上げられた棒みたいに一本になって寝ている。 体の中にある本体が抜け出して、その際入れ物である肉体を ぽいと投げ出して出かけてった、というような感じがする。 なんでそんなふうに感じるかというと 普段から監督の動きがそんな様子だからだ。
昨年末に無料プランを大幅制限したEvernote、一部機能を無料化
オンラインノートサービス「Evernote」は2月14日（現地時間）、無料プランの機能制限を緩和。これまで有料プラン向けに提供していた14の機能を無料プランのユーザーにも開放した。新たに無料化された機能は以下の通り。 ・履歴のメモと復元 ・オフラインノートとノートブック ・PDF 注釈 ・PDFエクスポート ・名刺スキャン ・スプレッドシートのプレビュー機能 ・Evernote にメモをメールで送信 ・メールによるノートの共有 ・カスタム グローバル キーボード ショートカット ・モバイルの「作成」ボタンをカスタマイズ ・カスタム テンプレート ・ブール検索（AND、OR、NOTなどの演算子を使った高度な検索機能） ・位置情報の検索 ・ドキュメントと画像の検索（無料プランでは2月14日以降に追加したコンテンツのみ対応）
2023年に読んでよかった技術書
おそらく 2023 年に Zenn で出す最後の記事になるかと思います。 タイトルの通り、2023 年に読んだ本の中で、特に素晴らしかったものをご紹介します。 とはいえあまり今年は技術書を読んだ印象がなく… というのも、特定の xx(例えば Next.js、Ktor)といった部類に関しては公式のドキュメントを読むことがほとんどになり、書籍に求めるのは公式ドキュメントに書かれていない何かや誰かの経験・ノウハウになったからだと思います。 この記事を書くにあたって今年読んだ本を振り返ってみても、やはり十数冊程度(それでも月に 1 冊は読んでた)のでインプット：アウトプットの割合的には良いバランスではないかと思っています。 ただ、先に述べた通り公式ドキュメントに書かれていないなにかを売っている本というのはどれも本当の意味で価値があるものであり、皆さんにも本当に意味のある情報にお金を使っていただける
2023年・新しく入ったメンバーの提案で開発チームが良くなったこと5選
このブログは、 IVRy 紅白Advent Calendar 2023の白組・17日目の記事です。 白組16日目は PdM佐瀬さん「IVRyなら上流からUX/UIデザイン業務が実践できます！」でした。明日はIVRyのVPoE近藤さんの「IVRyにおける開発生産性へのアプローチ～SPACEフレームワークの視点から～」についての記事が出ます。乞うご期待。 この記事について タイトル通り、2023年に提案されて改善した事を発表するのですが、裏返すと「そんなこともできてなかったのか」と見える内容もあるかもしれません。ネガティブに受け取られる可能性もあるかもしれませんが、IVRyのオープンな社風や、常に改善と変革に前向きな姿勢をアピールするためにも、この記事を執筆することにしました。 なお、課題を発見・解決しながら会社を大きくしていきたいエンジニアの皆さんは、ぜひブログ一番下のIVRyの採用情報から
「どうか旅の最後までおつきあいください。」NHKのドキュメンタリー『ニッポンおもひで探訪』がじわじわと話題に
浅原 昭生＠C103日曜東5ホール「ピ」40b @HEYANEKO 当方が制作協力したNHKの番組、 「ドキュメント20min. ニッポンおもひで探訪 ～北信濃 神々が集う里で～」が 次の日曜日（11/19）の深夜（24:00～）、NHK総合でオンエアされます。 nhk.jp/p/ts/YN5YRJ9KP… よろしかったら、チェックしてみてください。 #ドキュメント20min #ニッポンおもひで探訪 2023-11-16 07:02:34 ＮＨＫ長野放送局🍎 @nhk_nagano 俳優・ #宍戸開 さんが #飯山市 を訪れ 地域の伝統に触れる旅 🍂 ＃ドキュメント20min. どうかどうかどうか･･･ 旅の最後まで おつきあいください🙏 総合 📺 今夜 🌙 午前0:00～ （ 19日(日)深夜 🌙 ） 「ニッポンおもひで探訪」 nhk.jp/p/ts/YN5YRJ9KP… 2
設計ドキュメント腐る問題、Git管理で運用してみた結果 | フューチャー技術ブログ
はじめにTIG真野です。 秋のブログ週間2023 の3本目は、設計ドキュメントをGit管理して腐らせないようにがんばってみた話をします。 前段として6年前、「我々はいかにシステム開発におけるドキュメント腐る問題と戦えば良いのか」という記事を書いたのですが、その後の試行錯誤はどこにも残していないことに気づきました。普段のフューチャー技術ブログですとちょっと引け目を感じるテーマですが、秋の夜長を楽しむため読み物成分を多めに書くというテーマのこのブログリレーにピッタリな気がするため、この機会をお借りします。 ドキュメントも色々な種別があるかと思いますが、この記事では設計ドキュメントを指すことにします。設計ドキュメントは開発メンバーが参照するもので、ステークホルダーへの説明資料に引用して使うことはあれど、主目的は異なるという前提です。Design Docの場合もありますし、システム構成図、ERD、
構成図を描く際に気をつけていること - NRIネットコムBlog
こんにちは、越川です。 皆さんは構成図を描く機会ありますか？ 僕の場合、内部のメンバーやお客様との議論の場で、構成図を描いて図解ベースで説明することが多いです。実際に描いてみると色々と考慮すべき点が多く、今回は自分なりに普段意識している点を言語化してみようと思います。 なぜ構成図を描くのか 構成図を描く際に意識している３つのこと 1. 導線 2. 引き算思考 1. 主役を決める 2. 読者を想定する 3. 高さや大きさを揃える さいごに なぜ構成図を描くのか 構成図のメリットは相手に伝えたいことをシンプルに伝えられる点だと思います。文章で書くと沢山書かなければいけないことが構成図を使うとスムーズに相手に伝わります。例えば、以下の文章を読んでみて下さい。 ユーザーはDNS登録されたFQDNへHTTPSアクセスする CloudFrontはBehaviorに指定されたALBにHTTPSリクエスト
社内ドキュメントはなぜ更新されないのか？情報の鮮度を最小限の運用負荷で維持する「イミュータブルドキュメントモデル」のススメ - 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（株式会社エーピーコミュニケーションズ）さんが「カプセルト
意思決定できる人の手順の型 - Konifar's ZATSU
意思決定できる人は進める手順の型みたいなものを持っているように見える。逆に意思決定が遅かったりできなかったりする人は、進めるときに型のうちの何かが欠けているのかもしれない。 体系化された話は書籍で語られつくされているとは思うが、思考整理のために雑にまとめてみる。 最後は決めるだけだという考えを持つ 目的や満たしたいことを明確にする 最終的な決め方や期日を明確にする 選択肢を広げて考える 今は意思決定しない、という意思決定も選択肢に入れる 意思決定の軸を明確にする 軸をもとに定量/定性データを集める 軸をもとに選択肢を評価する 自分はこうしたいという"推し"を決めてたたき台にする ここまでの話をドキュメントにしている ここまでのプロセスに時間をかけない 意見を聞く人を見定めてフィードバックをもらう 最初に明確にした決め方で意思決定する 意思決定できない場合は決め方と期日と意思決定軸を再定義す
DNSの不正使用手法をまとめた技術ドキュメントの公開 - JPCERT/CC Eyes
はじめに 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
破綻したドキュメント管理、増え過ぎたプロダクトバックログ… 「Jira」「Confluence」などの活用失敗から学ぶツール運用のコツ
Jira SoftwareやTrelloなどを中心としたPMが経験してきたプロダクト管理ツールの失敗や改善を語る「本当に使いこなせてる？プロダクト管理ツールの失敗&改善PMトーク【開発PM勉強会 vol.20】」。ここで株式会社ビズリーチの菊池氏が登壇。ドキュメント管理とプロダクトバックログの失敗から学ぶツール運用のコツについて紹介します。 菊池氏の自己紹介 菊池信太郎氏（以下、菊池）：ビズリーチの菊池から、10分枠で話をします。今日のテーマは「失敗から学ぶドキュメントとチケット運用のコツ」ということで、今まで経験したところで「こういうアンチパターンがあったよ」「こういう改善をしたよ」というようなところをお話しできればと思っています。 自己紹介を軽くすると、（私は）2018年からビズリーチで働いています。ビズリーチサービスを作っていて、プラットフォーム開発部の部長をしています。また、201
アメリカの職場ではなぜドキュメントも無いのに人が去っても問題ないのだろう？｜牛尾 剛
アメリカの職場にいると、日本にいるときよりも身近でレイオフだとか、職を変えるというのを頻繁に見かける。先日もそういう場面があったのだが昔日本で働いていた時のことを思い出した。 ドキュメントを書く理由 日本のソフトウェア企業にいたときは、「納品物であるから」という理由以外にも、「人がいなくなったときに会社が困るから」という理由でもドキュメントを書くことが推奨されていた。しかし、少なくとも今の職場ではそんな理由でドキュメントを書くのは推奨されていないのに、なぜ問題にならないのだろうとふと思った。 うちのマネージャは、バディ制ににして、みんな休暇できるようにしようとは言っているが、多分本当に退職対策ではないと思う。 チームのメンバーが抜けたときも、「とても残念で、ワークロードをどうしようという問題はあるけど、彼女の門出を祝福しよう」言っていた。つまり、こちらでも「工数」は問題になるけど、「引継ぎ
Web標準に新たなステータス「Baseline」が登場。変化し続けるWeb標準のうちWeb開発者が安心して使える機能群を示す。MDNドキュメントなどで表示開始
Web標準に新たなステータス「Baseline」が登場。変化し続けるWeb標準のうちWeb開発者が安心して使える機能群を示す。MDNドキュメントなどで表示開始 Web開発者の開発体験を改善することなどを目的としたW3CのWebDX Community Groupは、つねに新たな機能などが登場し変化し続けるWeb標準のうち、Web開発者が安心して使える機能群を示す新たなステータス「Baseline」を発表しました（Googleによる発表、MDNによる発表）。 現在、Web標準はリビングスタンダードとしてつねにアップデートが行われており、ChromeやFirefox、Safariなどの主要なWebブラウザは、Web標準で新たに策定される機能をそれぞれ実装し、最新版に反映させています。 そのため、それぞれのWebブラウザがWeb標準のどの機能をいつ頃実装し、最新版に反映させるのかは時期が異なりま
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
「Pythonのドキュメントでも読むか～」「え、何その裏技」 - Qiita
テクニカルライティングの基本 2023年版
