Eraser – Docs and Diagrams for Engineering TeamsAll-in-one markdown editor, collaborative canvas, and diagram-as-code builder
JSON Canvas
An open file format for infinite canvas data. Infinite canvas tools are a way to view and organize information spatially, like a digital whiteboard. Infinite canvases encourage freedom and exploration, and have become a popular interface pattern across many apps. The JSON Canvas format was created to provide longevity, readability, interoperability, and extensibility to data created with infinite
TypeScript のような構文で OpenAPI のスキーマを定義する TypeSpec
import "@typespec/http"; using TypeSpec.Http; model User { id: string; name: string; birthday?: utcDateTime; address: Address; } model Address { street: string; city: string; state: string; zip: string; } @route("/users") interface Users { list(@query limit: int32, @query skip: int32): User[]; create(@body user: User): User; get(@path id: string): User; } openapi: 3.0.0 info: title: (title) versio
社内ドキュメントはなぜ更新されないのか？情報の鮮度を最小限の運用負荷で維持する「イミュータブルドキュメントモデル」のススメ - KAKEHASHI Tech Blog
はじめに こんにちは。カケハシの各プロダクトを支えるプラットフォームシステムの開発チームでテックリードを担当しているkosui(@kosui_me)です。 プロダクト開発の世界では、明瞭な社内向けドキュメントを書くための方法が数多く提案されてきました。読者の中には、製品要求を明瞭にするためにPRD (Product Requirements Document、製品要求仕様書) を書き、プロジェクトの背景から全体の設計やその代案について明瞭にするためにDesign Docsを書き、アーキテクチャに関する意思決定の記録を明瞭にするためにADR(Architecture Decision Record) を書いてきた方も数多くいらっしゃると思います。 しかし、どんな素晴らしいドキュメントも、何故か更新されなくなります。新メンバーへのオンボーディングのためにインフラ構成図を検索したあなたが見つけた
Nomnoml
Association types association - association -> association <-> dependency --> dependency <--> generalization -:> implementation --:> composition +- composition +-> aggregation o- aggregation o-> ball and socket -o) ball and socket o<-) ball and socket ->o note -- hidden -/- Class diagram types [class] [<abstract> abstract] [<instance> instance] [<reference> reference] [<package> package|components
Web API設計時に使われ方の想定を添えると良い。けどより良いやり方を知りたい - valid,invalid
先日登壇したイベントにて、仕事で協業したモバイルエンジニアから「Web APIのドキュメントに使われ方の想定が添えられていてありがたかった」とフィードバックをもらった。 具体的にはX post (以下、tweet) に添付した画像のような感じで、Web API (以下、API) が呼び出される画面・タイミングの想定、レスポンスの使われ方の想定などをUIのスクショとともに記述する、というもの。 API設計時にこういう使われ方の想定を添えると認識揃えやすくてありがたい、とモバイルエンジニアに喜ばれました#B43_techtalk pic.twitter.com/XLB3g6fCLZ— ohbarye (@ohbarye) 2023年8月3日 他にもこんなのとか。 APIレスポンスの使われ方の想定を書いているようす このことについて思ったよりもイベント内外で反響があったので書く。 ドキュメントの
意思決定できる人の手順の型 - Konifar's ZATSU
意思決定できる人は進める手順の型みたいなものを持っているように見える。逆に意思決定が遅かったりできなかったりする人は、進めるときに型のうちの何かが欠けているのかもしれない。 体系化された話は書籍で語られつくされているとは思うが、思考整理のために雑にまとめてみる。 最後は決めるだけだという考えを持つ 目的や満たしたいことを明確にする 最終的な決め方や期日を明確にする 選択肢を広げて考える 今は意思決定しない、という意思決定も選択肢に入れる 意思決定の軸を明確にする 軸をもとに定量/定性データを集める 軸をもとに選択肢を評価する 自分はこうしたいという"推し"を決めてたたき台にする ここまでの話をドキュメントにしている ここまでのプロセスに時間をかけない 意見を聞く人を見定めてフィードバックをもらう 最初に明確にした決め方で意思決定する 意思決定できない場合は決め方と期日と意思決定軸を再定義す
DB設計の共有で疲弊してない？dbdocsのすゝめ
DB設計の管理や作成に疲弊してません？こんにちは。ukmshiです。今日はDB設計の共有と管理に便利なツール、dbdocsについてお話しします。dbdocsを使えば、設計の可視化や共有がめちゃくちゃ簡単になるんです。今回は、その魅力と利点、そして実際の使い方について詳しく説明します。 dbdocsとは？ dbdocsは、コードベース（DBML）でDB設計を管理し、URLで共有することが可能なツールです。データベースのテーブル構造や関係性を可視化し、それを他のチームメンバーやステークホルダーと手軽に共有することができます。 DBMLについてはこちらを参考に dbdocsの利点 dbdocsの利点について詳しく見ていきましょう。 無料 まず最初に、dbdocsは基本無料です。コストを気にせずに利用できるので、チームの誰もがアクセス可能です。 コードベースで管理 dbdocsはコードベースでDB
大事だけど AWS 構成図では省略してしまうことが多いサービスについて - サーバーワークスエンジニアブログ
コーヒーが好きな木谷映見です。 今回は小ネタです。AWS 構成図を書く際、省略してしまうことが多いサービスについて思いを馳せました。 よくある？構成図 リージョン アベイラビリティゾーン ルートテーブル AWS IAM インスタンスプロファイル Amazon EBS Elastic IP Elastic network interface（ENI） セキュリティグループ セッションマネージャーする時のエンドポイント 最終構成図 終わりに よくある？構成図 よくあると思われる構成図を描いてみました。 AWS になじみがある方から見ると、 「ふむ、パブリックサブネットとプライベートサブネットに 1 台ずつ EC2 インスタンスがあって、プライベートサブネットのインスタンスにはセッションマネージャーでログインするのかな？S3 バケットもあるな」 くらいの想像ができるかもしれません。 リージョン
読みやすいドキュメントを書くために今日からできる7つのこと｜壮｜Masato Tanaka
こんにちは。壮（@sew_sou19）と申します。 メガベンチャー企業でエンジニアとして働いています。 エンジニアにジョブチェンジした当初は、ドキュメントの書き方なんてこれっぽっちも分かりませんでした。読みやすいドキュメントを書くことが本当に苦痛だったのですが、考えて、試行錯誤し続けた結果、以下のような評価を得るに至りました。 リーダーから「君は情報の整理が上手でドキュメントが本当に読みやすい。チーム全体の能力向上に繋げたいからドキュメント書く際のポイント共有してほしい」と言われたので、意識していることを言語化しつつテクニカルライティングの本でインプットしてるけど、学びが多い。ついでにnoteにもまとめてる — 壮 (@sew_sou19) November 28, 2022 そこでこのnoteでは、僕がドキュメントを作成するときに、特に意識して実践している7つのことを書きます。（本当は2
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
Showcasing your API technical writer portfolio and projects — guest post by Peter Gustafson
GitHub - drawdb-io/drawdb: Free, simple, and intuitive online database design tool and SQL generator.
GitHub - plantuml/plantuml-core: Core library of PlantUML that runs completely on javascript without needing java/servers
TypeSpec
Scrapboxの哲学 - 橋本商会
Eraser – Docs and Diagrams for Engineering Teams
日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード / Architectural Decision Records
テクニカルライティングの基本 2023年版
GitHub - 1f408/cats_dogs: CAT'S DOCument System
Obsidian - Sharpen your thinking
