tblsのViewPoint機能を用いたGithub Actions上でのDBドキュメントの自動生成 - Safie Engineers' Blog!
この記事はSafie Engineers' Blog! Advent Calendar 2日目の記事です。 セーフィー株式会社でテックリードをやっております鈴木敦志です。 セーフィーはクラウドカメラのSaaSを提供しており、現在22万台程度のデバイスに対してカメラ映像をクラウドから視聴する機能を提供しています。 それに加えエンタープライズ向けの権限管理機能や社内向けの販売管理ツールなど複数のサービスを運営しており、各サービスでMySQLのDBを共有しているためDBのテーブル数が肥大化し構造がわかりにくくなり、新機能開発の妨げとなっていました。 本稿ではデータベースのドキュメンテーションツールである tbls を導入し、DBスキーマ管理ツール skeema、ドキュメント生成ツール mkdocs、Github Actionsなどと組み合わせてスキーマ管理からドキュメント生成までをやっていきます
「ドキュメントの書き方」を体系的に学んだことがないエンジニアへ 書籍『エンジニアのためのドキュメントライティング』の概要
インフラエンジニア向けの書籍を取り上げ、著者と出会い、楽しく本を知り、仲間を作る場所である「インフラエンジニアBooks」。ここで、『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』の翻訳を担当した岩瀬氏が登壇。まずは、本書籍の概要について話します。 本セッションの対象者と、セッションのゴール 岩瀬義昌氏：ご紹介いただきました、岩瀬と申します。よろしくお願いします。『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』は、もともと『Docs for Developers: An Engineer’s Field Guide to Technical Writing』という洋書だったんですが、その翻訳をして、今回この機会をいただいています。 余談ですが、APC（株式会社エーピーコミュニケーションズ）さんが「カプセルト
GitHub - google/typograms
Typograms (short for typographic diagrams) is a lightweight image format (text/typogram) useful for defining simple diagrams in technical documentation, originally developed here. See it in action here: https://google.github.io/typograms/ Like markdown, typograms is heavily inspired by pre-existing conventions found in ASCII diagrams. A small set of primitives and rules to connect them is defined,
きれいなコードを書けという話について - Software Transactional Memo
前回のブログから90日以上経ってしまったので広告が載ってしまったから短文でもアウトプットしておく。 プログラマとして仕事をしているとコードと向き合っている時間の9割以上は既存のコードを読んでいる、だから読みやすさは重要である、という言説は耳にタコができるほど誰もが言っている。 仕事で書かれるコードが誰のレビューも通ること無くマージされている現場は凄惨だが、自分より明らかに経験を積んだ人たちが何度もレビューを重ねたコードが読みやすいかというとそうとは限らない。良いコードが守るべきルールをすべて守っていても不可解なコードはあるし、どんなに読みやすいコードでも数千行の規模になってくるとやはり脳内からこぼれて一度に覚えておける範囲からはみ出る。 変数名や関数名をわかりやすくするとか不必要な技巧を凝らさないとかわかりやすい設計にするとか主観的な事を偉そうに語る本は山ほどあり、それらの本を崇める事は悪
大事だけど AWS 構成図では省略してしまうことが多いサービスについて - サーバーワークスエンジニアブログ
コーヒーが好きな木谷映見です。 今回は小ネタです。AWS 構成図を書く際、省略してしまうことが多いサービスについて思いを馳せました。 よくある？構成図 リージョン アベイラビリティゾーン ルートテーブル AWS IAM インスタンスプロファイル Amazon EBS Elastic IP Elastic network interface（ENI） セキュリティグループ セッションマネージャーする時のエンドポイント 最終構成図 終わりに よくある？構成図 よくあると思われる構成図を描いてみました。 AWS になじみがある方から見ると、 「ふむ、パブリックサブネットとプライベートサブネットに 1 台ずつ EC2 インスタンスがあって、プライベートサブネットのインスタンスにはセッションマネージャーでログインするのかな？S3 バケットもあるな」 くらいの想像ができるかもしれません。 リージョン
HashiCorp、ドキュメントの作成／レビュー／共有などを容易にする「Hermes」ドキュメントマネジメントシステムをオープンソースで公開
HashiCorp、ドキュメントの作成／レビュー／共有などを容易にする「Hermes」ドキュメントマネジメントシステムをオープンソースで公開 TerraformやVagrantなどで知られるHashiCorpは、「急成長するグローバル企業や遠隔地に拠点を置く企業にとって、書く文化は必要不可欠なものだと考えています（we also believe a culture of writing is a necessity for a fast growing, global, remote-oriented organization.）」として、同社内でも文書による情報共有文化が積極的に行われていると説明しています。 その同社が社内で開発し利用しているドキュメントマネジメントシステム「Hermes」を、オープンソースとして公開しました。 We are pleased to announce th
データベースドキュメント生成コマンド tbls 更新情報（Mermaid対応 / schema.json / tbls outの強化） - Copy/Cut/Paste/Hatena
久しぶりのtblsの新機能紹介エントリです。 ドキュメントのER図出力にMermaidを指定できるようになりました ER図の出力フォーマットにMermaidを指定できるようになりました。次のように er.format: セクションか --er-format オプションに mermaid を指定することで変更できます。 er: format: mermaid 開発裏話 GitHubがMermaid対応したことで「tblsもMermaid対応してほしい」という要望や提案は以前より多く受け取っていました。 しかし、個人的にあまりメリットを見出せずそのままPull Request待ちとなっていたのですが、今回エイッと作ってみました。 Mermaid対応をするにあたって1つとても面倒な仕様がありました。それはMermaidはER図の多重度（カーディナリティ）の指定が必須となっていることでした。 もと
[Doc] 要件定義書テンプレート・要件定義書の書き方 - Qiita
(GPT補完) 下記ドキュメントバージョンに関する注意点です。 バージョン番号のルールを定める：バージョン番号は、どのようにつけるかルールを定め、チーム全員が同じ理解で使用するようにする必要があります。たとえば、変更内容によって数字がどのように増えるか（major, minor, patch）、何桁で表現するかなど、具体的に決めておくことが重要です。 変更履歴を明確にする：どのような変更があったのか、それがどのバージョンで実施されたのかを明確にすることが必要です。これにより、何らかの問題が発生した場合に、どのバージョンから問題があるのか特定することができます。 ドキュメントの保存場所を一元化する：ドキュメントのバージョン管理には、ドキュメントを保存する場所を一元化することが重要です。それにより、異なるバージョンのドキュメントが、複数の場所に分散してしまい、誤ったバージョンが使用されることを
![[Doc] 要件定義書テンプレート・要件定義書の書き方 - Qiita](https://cdn-ak-scissors.b.st-hatena.com/image/square/524aefbbe8f601d7a9248f00b4ca010578396064/height=288;version=1;width=512/https%3A%2F%2Fqiita-user-contents.imgix.net%2Fhttps%253A%252F%252Fcdn.qiita.com%252Fassets%252Fpublic%252Farticle-ogp-background-9f5428127621718a910c8b63951390ad.png%3Fixlib%3Drb-4.0.0%26w%3D1200%26mark64%3DaHR0cHM6Ly9xaWl0YS11c2VyLWNvbnRlbnRzLmltZ2l4Lm5ldC9-dGV4dD9peGxpYj1yYi00LjAuMCZ3PTkxNiZoPTMzNiZ0eHQ9JTVCRG9jJTVEJTIwJUU4JUE2JTgxJUU0JUJCJUI2JUU1JUFFJTlBJUU3JUJFJUE5JUU2JTlCJUI4JUUzJTgzJTg2JUUzJTgzJUIzJUUzJTgzJTk3JUUzJTgzJUFDJUUzJTgzJUJDJUUzJTgzJTg4JUUzJTgzJUJCJUU4JUE2JTgxJUU0JUJCJUI2JUU1JUFFJTlBJUU3JUJFJUE5JUU2JTlCJUI4JUUzJTgxJUFFJUU2JTlCJUI4JUUzJTgxJThEJUU2JTk2JUI5JnR4dC1jb2xvcj0lMjMyMTIxMjEmdHh0LWZvbnQ9SGlyYWdpbm8lMjBTYW5zJTIwVzYmdHh0LXNpemU9NTYmdHh0LWNsaXA9ZWxsaXBzaXMmdHh0LWFsaWduPWxlZnQlMkN0b3Amcz0wODBjMWQxOWYwOTg5NDI4YzZiMWRmYWE2YmNmMzI1OA%26mark-x%3D142%26mark-y%3D112%26blend64%3DaHR0cHM6Ly9xaWl0YS11c2VyLWNvbnRlbnRzLmltZ2l4Lm5ldC9-dGV4dD9peGxpYj1yYi00LjAuMCZ3PTYxNiZ0eHQ9JTQwc3lhbnRpZW4mdHh0LWNvbG9yPSUyMzIxMjEyMSZ0eHQtZm9udD1IaXJhZ2lubyUyMFNhbnMlMjBXNiZ0eHQtc2l6ZT0zNiZ0eHQtYWxpZ249bGVmdCUyQ3RvcCZzPTQ5NDc0M2ZjOWU5MDg1NWM3YzExNjg3ZjA1ZDIwMjRl%26blend-x%3D142%26blend-y%3D491%26blend-mode%3Dnormal%26s%3D3c956ec09e55703533b9a2487bd3c5f6)
安全安心にソフトウェア開発を行うためのDesign Doc導入ガイド｜面川泰明
みなさん、コードを書く前に設計書を書きますか？ 書くか書かないかは人それぞれだと思いますが、「設計」というプロセス自体は意識的であれ無意識的であれエンジニアであれば全員やっていることだと思います。 今回は設計プロセスの改善という文脈で私たちがDesign Docという仕組みを導入したことについて共有しようと思います。もし同じような状況を経験している人がいたら参考になれば幸いです。 導入の背景まずは導入するに至った状況からお話します。 私たちのサービスは、利用していただくユーザーの数が増加しています。それに伴って品質のハードルも上がってきました。サービスに障害が発生するとユーザーさんに大きな損害を出してしまうことになるからです。そこで今まで以上に安全にサービスを開発できる仕組みづくりが必要になりました。ですが、実現のためには大きく2つの課題がありました。 課題1. 開発スピードが徐々に鈍化し
障害報告書を書こう！ - Qiita
担当しているITサービスなどに何かしらのインシデントや障害が発生した時に、対処後のアクションとして報告書を提出して事象の内容を報告（レポート）する場合がある。 提出先は会社の偉い人だったりクライアントだったり。場合によってはユーザー向けに発表したり。事の顛末を報告して「今後同様のことを起こさないように努力します、ごめんなさい」をするのだ。どのように再発防止の努力するのかを書くものでもある。 主にクライアント向けのビジネス内容ではあるが、自分が使っているテンプレパターンを共有するので参考にしてもらえればと思う。1 全般的なポイント 心得のようなもの。次の点は留意してて欲しい。 淡々と冷静な説明をこころがける 当然のことながら事実は脚色しない。無駄な修飾も要らない。客観的な事実を簡潔に述べる。 例： ❌「一生懸命頑張って対応したが…」 ❌「寝ないで対応したが…」 ❌「本当の原因は…」 できるだ
GoogleのDesign Docsから学ぶソフトウェア設計 - Qiita
概要 Design Documentと聞くと何を想像しますか？ 一般的にDesign Documentが指すのは設計書であることが多いのではないでしょうか。 設計書、簡単に説明するのであればソフトウェアを「どうやって作るの？」を説明したドキュメントです。 Googleではソフトウェアエンジニアリング文化における重要な要素として、今回お話ししていくDesign Docsと呼ばれるものがあります。 Design Docsとは？ Design Docsとは、開発者がコーディングに着手する前にソフトウェアシステムまたはアプリケーションの開発する人が作成するドキュメントです。 => ソフトウェア設計における仕様書や設計書とは別物と捉えた方がよいです。 仕様書、設計書は作成した上でのDesign Docsの作成となるようです。 このドキュメントには、高レベルの実装戦略と主な設計の決定事項がまとめられて
【メモ】良いDesign Docs(Software Design Document)を書くためのリソース集
自分が良い Design Docs(Software Design Document)を書くために、読んだ/参考になったリソース集 一覧 Design Docs とは Design Docs at Google デザインドック(Design Doc)について デザインドックで学ぶデザインドック 残業も減らせる!? 上級エンジニアになるための Design Doc 超入門 「Design Doc」って何なのか？ What Is A Design Doc In Software Engineering? (full example) What is a Design Doc: Software Engineering Best Practice #1 https://github.com/kaiinui/note/blob/master/Design--Designdoc.md Googleの
技術系イベント登壇における資料作成のコツ - 電通総研 テックブログ
みなさんこんにちは、電通国際情報サービス（ISID）Xイノベーション本部ソフトウェアデザインセンターの佐藤太一です。 少し前になりますが4/23に、私はGo Conference 2022 SpringにおいてGo で RDB に SQL でアクセスするためのライブラリ Kra の紹介というタイトルで登壇しました。 登壇時の資料はこちらです。 このエントリでは、スライドを作成する際に私が考えていることや、情報を整理する方法について説明します。 伝えたいメッセージを作りこむ アイディア出し 初期のアイディア出し例 アイディアの統合 アイディアの統合例 メッセージの絞り込み メッセージの例 今回のメッセージ 伝えたい情報を構造化する 構造のテンプレート 論理の順序を整理する まとめ 伝えたいメッセージを作りこむ 私が技術系のイベントに登壇する際に最も重視しているのがメッセージの作りこみです。
ドキュメントに固執せよ - gfnweb
どうして人間集団はこんなにも知見の共有を円滑にできないのか？ 改善にはドキュメントにまつわる各個人の心構え・制度設計・技術的解決の全部が必要だという話をしたい． ここでテーマにしているのは，著名OSSなど世の中にいくらでも知見が転がっている対象ではなく，特に企業内の十数人のチームでクローズドに開発しているなどして集合知に頼れない状況下でのドキュメントについてである． 非常に乱暴な言い方をするなら，「コードとか大部分は誰でも書けるようになるものなんよ，そんなところにマッチョイズムとか感じなくてええねん，我々の知的体力や組織性が真に試されるのはドキュメントちゃうんか」という気持ちです — 画力・博士号・油田 (@bd_gfngfn) June 3, 2022 ドキュメントに書く内容の必須項目或るシステム（ソフトウェアなど）について，そのシステムのことを全く知らない人を想定読者としたドキュメント
わかりやすいシステム構成図の書き方 - Qiita
わかりにくいシステム構成図とは こんなシステム構成図を書いてないでしょうか？ このシステム構成図のわかりにくい点が３つあります。それは 製品名は書いてあるが「役割」が書いていない データと処理が区別できない データの流れと制御の流れが区別できない の３つです。 わかりやすいシステム構成図 これら３つのわかりにくい点を改善したわかりやすいシステム構成図が↓です ポイントを解説していきます ポイント1. 製品名称ではなく「役割」を書く システム構成図には製品名称ではなくシステムコンポーネントの「役割」を書きます。 役割とは、例えば〇〇データや〇〇処理といったことであり、それを読むだけでシステムの動きを理解できる文字列です。役割をかかずに製品名称のみを書いてしまうと、その製品を知らない人が見たときに理解できません。例えば「Cloud Pub/Sub」という製品はGCPというパブリッククラウドの分
HTTPキャッシュに学ぶ、無理のないドキュメント更新運用
LAPRAS株式会社でSREをしていますyktakaha4と申します 🐧 私は 2021 年の 1 月に LAPRAS に入社 したのですが、 入社以来ほそぼそとやってきた、ドキュメンテーションに関する取り組みについて一年ほど運用し一区切りがついたので、その話をしたいと思います✍ ことのおこり 現在弊社には正社員・業務委託あわせて 18 名程度のエンジニアが在籍 していますが、 私が入社した頃はエンジニアが7名程度、かつ全体の人数に対して在任歴の長い人が多かったこともあり、 開発者が参照するドキュメント管理について、比較的牧歌的な運用がなされていました 🐑 具体的には、開発環境の構築方法が古い手順のまま放置されていたり、オンボーディングに使うドキュメントが口伝されていたりと、 ドキュメント自体は存在するものの、それらが 古くなっていたり一覧化が不十分であることが検知できず、時間経過に伴
Writing better release notes
31st January 2022 Release notes are an important part of the open source process. I’ve been thinking about these a lot recently, and I’ve assembled some thoughts on how to do a better job with them. Write release notes. Seriously—if you want people to take advantage of the work you have been doing to improve your projects, you need to tell them about it! Include the date. The date matters a lot, b
【翻訳】Googleのエンジニアがソフトウェア開発する時に必ず書くドキュメント「Design Docs at Google」 - BppLOG
Googleでの「Design Docs」とは 2007年の Google Developer Day Tokyo での鵜飼氏のプレゼンによると「Google で必ず書くことになっているドキュメント」であり、「プロジェクト立ち上げ時の 1～2週間をかけて書く」ものです。 今回は Google のソフトウェアエンジニアである @cramforce 氏が自身のブログで「Googleでの Design Docs」について解説している記事を公開されていたため、氏の許可を得て翻訳しています。 原文： www.industrialempathy.com 関連書籍： Googleのソフトウェアエンジニアリング ―持続可能なプログラミングを支える技術、文化、プロセス オライリージャパンAmazon 読了目安：11分 (目次) デザインドキュメント の解剖学 文脈と範囲 目標と非目標 実際のデザイン システ
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
テクニカルライティングの基本 2023年版
テクニカルライティングの基本
