Obsidian（オブシディアン） と出会ってまだ3日目ではありますが、ここ最近で一番興味をそそられるアプリだったので紹介します。 A second brain, for you, forever. https://obsidian.md/ 出会いの経緯 を眺めていたときに一つの記事が目に付きました。 私がソフトウェア開発者として Notion から Obsidian に移った理由トップ3 何やら少し挑戦的なタイトルです。私も情報を整理するときに Notion はよく使用しています。不満がないとは言わないものの、Notion の機能を超える情報整理ツールは中々ないことくらいはわかります。 気になった記事は、まず読んでみることです。 読みながらの感想 "Obsidian" ……なんて読むの？ｶﾀｶﾀ……オブシディアン。いやー、スペルも読み方も覚えられないなぁ……。どんな意味なの？ｶﾀｶﾀ……

技術発信活動の第一人者が技術発信をはじめたきっかけ、技術発信をすることで得たことなどを話す「今年こそは継続的にアウトプットすると決めた方向けに語る技術発信の取り組み方　#技術発信2022」。ここでピクシブ株式会社のうさみけんた氏が登壇。自身の経験をもとに、技術発信の信頼性を高めるポイントを紹介します。 うさみ氏の自己紹介うさみけんた氏（以下、うさみ）：今日は「技術発信の信頼性を高める10（イチゼロ）のポイント」ということで話したいと思います。 私は「うさみ」といいます。ふだんはピクシブという会社で、ピクシブ百科事典とか、PHPで書かれているWebサービスの開発をしています。個人ではEmacsでPHP開発する環境を作っていたりとか。2022年はあまりできていませんが、イベントやカンファレンスのスタッフ、実行委員として参加することがあります。 今回のお題ですが、「技術発信の信頼性を高める10の

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

howto-tech-docs.md 技術文書の書き方 このメモは、私（@ymmt2005）が長年にわたってソフトウェアプロダクト開発に関わってきて 2022年現在こうしたほうが良いと考えているベストプラクティスです。 科学的な分析等に基づくわけではない経験則であるため、今後も随時見直すことがありますし、 ここに書いてあることが常に正しいわけでもあらゆるソフトウェア開発に適するわけでもありません。 しかしながら、実務経験が豊富で、モダンな技術スタックに明るいエンジニアの経験則は一定の 役に立つのではないかと考えて記します。 技術文書とは ここでは、ソフトウェア開発で技術者が書くべき文書ということにします。 ソフトウェアエンジニアにも役割がいろいろあり、アーキテクトと independent contributor では書く文書が違うということはあるでしょうけれど、ここではごっちゃにします。

最初に 公式のガイドライン AWSが配布しているツールキットの中に基本的なガイドラインが記載されています。 描き方に正解はない こちらの記事のあるようにアーキテクチャ図に正解はなく、伝えたいことが適切に伝わるということが大切だと思います。 伝えたい内容や伝える相手によって重点や粒度を変えることを心がけています。 描画ツール diagrams.net（Draw.io）を使ってます。 意識していること アイコンは最新バージョンを使用する AWSのアイコンは定期にアップデートされるので最新のアイコンを使うようにします。 ちなみにdiagrams.netでEC2と調べると古いアイコンが先頭に出てきたので意識していないとこちらを使いがちかもです。 アイコンのバージョンを混ぜない アイコンは最新バージョンを使用すると同じような内容ですが、複数バージョンのアイコンが混在しないようにします。以下の図ではE

You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert

はじめに データベース設計のER図について、VSCodeなどで作成する以下３つの方法を比較した記事です。 Draw.io PlantUML Mermaid 以前、Webアプリケーションを作成した際には、 Draw.io を使用して、作図しました。 （そのアプリのER図を今回サンプル図としています） 最近、 PlantUML を利用するようになり、ER図や、シーケンス図、クラス図の作図に利用しているのですが、とても編集しやすいと感じています。 ただ、どのツールにも、一長一短あるかと思いますので、それぞれ以下目次の内容を書いて、ご紹介したいと思います。 目次 1. Draw.io 1-1. VSCodeでの使い方 1-2. ER図 1-3. 感想 2. PlantUML 2-1. VSCodeでの使い方 2-2. ER図 2-3. 感想 3. Mermaid 3-1. VSCodeでの使い方

Diagram as Code6 different ways to turn code into beautiful architecture diagrams

担当しているITサービスなどに何かしらのインシデントや障害が発生した時に、対処後のアクションとして報告書を提出して事象の内容を報告（レポート）する場合がある。 提出先は会社の偉い人だったりクライアントだったり。場合によってはユーザー向けに発表したり。事の顛末を報告して「今後同様のことを起こさないように努力します、ごめんなさい」をするのだ。どのように再発防止の努力するのかを書くものでもある。 主にクライアント向けのビジネス内容ではあるが、自分が使っているテンプレパターンを共有するので参考にしてもらえればと思う。1 全般的なポイント 心得のようなもの。次の点は留意してて欲しい。 淡々と冷静な説明をこころがける 当然のことながら事実は脚色しない。無駄な修飾も要らない。客観的な事実を簡潔に述べる。 例： ❌「一生懸命頑張って対応したが…」 ❌「寝ないで対応したが…」 ❌「本当の原因は…」 できるだ

AppleやGoogleといったOSを開発するメーカーは、自社プラットフォーム向けのアプリをリリースする開発者向けに、どのようにデザインを構築していけばいいのかをまとめたガイドラインを作成し公開しています。Appleの「Human Interface Guidelines」は、言葉・画像・デザインをどのように選択すればユーザーが簡単にコンテンツや機能を使えるようになるかをまとめたもので、開発者だけでなく多くの人にとって参考になる内容が多く含まれたものとなっています。 Inclusion - Foundations - Human Interface Guidelines - Design - Apple Developer https://developer.apple.com/design/human-interface-guidelines/foundations/inclusion

2018年6月1日に株式会社メルペイに入社して、4年が過ぎました。入社当時は、定年が60歳と聞いていたので、1年半の勤務だと思っていましたが、実際の定年は65歳であり定年まであと2年半です。 ソフトウェアエンジニアにとって重要な能力と（私は考えるが）、身に付けるのが難しいのが現実だと、この4年間で再認識したのは次の三つです。 開発の最初にAPI仕様をきちんと書けるソフトウェアエンジニアは少ない テストファースト開発を行っているソフトウェアエンジニアは少ないか、いない Tech Blogなどの執筆で、読み手を意識して、分かりやすい文章を書く、ソフトウェアエンジニアは少ない API仕様については、このブログでも何度か書いています（「API仕様を書く」）。テストファースト開発についても、「テストファースト開発」を書いています。分かりやすい文章については何も書いていないですが、「伝わる技術文書の書

「AWSの各サービス、冒頭の説明文見てもどういうものなのか全然分からなくない？　もしAWSがカップラーメン発売したらこんな感じの紹介してると思う」──こんな考えから生まれた、“AWS公式サイト風”にカップ麺を紹介する画像が話題だ。Twitterでは「もはやAWS文学」などの反応があり、5月10日時点で1万3000いいねを集めている。 作成したのは、書籍「OpenCVではじめよう ディープラーニングによる画像認識」などを執筆するKazuya Gokitaさん（@kazoo04）。画像では、カップ麺を「Amazon CR」というサービスだと仮定し、特徴を以下のように説明している。 Amazon CRは、わずかなアクションで素早く安全に喫食可能なフルマネージド統合サービスです。CRを使用すればホットスタンバイ状態のH2OあるいはRawとして麺、醤油または味噌、また葱、肉などを単一のフローとして提

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

たまには軽い話題をば。 自分の中で信頼できるエンジニアかどうか？を見極めるひとつの指標で「込み入った議論の時に図を書くかどうか」というのがあります。 今までの経験上、図を書く派のエンジニアは割と良い感じの人が多かったので採用している指標なのですが、何故これが機能しているかというのを改めて考えてみた。 他者の認知負荷を理解している コンテクストを合わせることにコストをかけられる意識がある 自分の思考の整理するツールとして図を扱えている ザッと挙げましたが、この３つが機能している要因なのかなという気がしています. 他者の認知負荷を理解している あれやこれやエンジニア間で技術議論している中で、「Aさんはこの領域に詳しいけどBさんはこの領域にはほどほど詳しいくらいだな」という個々のレベル差に応じて認知の負荷がかかります。ただでさえ議論していると結構なスピードで話が展開されていくので、認知負荷が更に

はじめに プロジェクトに参加しているメンバーがうまく環境に適用できずに離脱することがあり、ともすれば、身体を壊してしまうケースもあります。これは新規メンバーに限定されず、既存のメンバーでも、プロジェクトや本人の状況、その役割が変われば発生し得ると思っています。 そういったことを回避できた状態を想像した時にプロジェクトに浅瀬があったら良いのではというイメージからこの言葉が浮かんだのだと思います。2年ほど前のメモ書きにこのタイトルが残されていて、今見直した時にすごくしっくり来ました。 メモ書きを発見したツイート この「プロジェクトに浅瀬を作る」とは、どういうことなのか、改めて深堀したいと思います。 どういうこと？ 溺れないようにするのが目的 監視員が必要のない状態が理想 溺れないようにするのが目的 溺れるというのは、闇雲に時間がかかってしまい心身ともに疲弊してしまうイメージです。不慣れなため必

マイクロソフト、JavaScriptに型宣言を追加しつつトランスパイラ不要の「Types as Comments」をJavaScript仕様策定会議のTC39に提案へ マイクロソフトのTypeScript開発チームは、JavaScriptのコードにTypeScript互換のアノテーション（注釈）を加えることで変数や関数などの型を宣言し、エディタなどのツールで型情報を活用可能にする一方、実行時にはJavaScriptエンジンがアノテーションを無視することでコードをトランスパイラで変換することなく実行可能なJavaScriptの新構文「Types as Comments」を、JavaScriptの使用を策定する「TC39」（Ecma International, Technical Committee 39）に提出する計画を明らかにしました。 このマイクロソフトの発表には、TC39の共同議長で