「Design doc とは何か」・「何を書けばよいのか」を説明するスライドです。 関連するプレゼンテーション「読みやすいコードの書き方」: https://gist.github.com/munetoshi/65a1b563fb2c271f328c121a4ac63571 © 2023 Munetoshi Ishikawa, supported by LINE corporation
コーヒーが好きな木谷映見です。 今回は小ネタです。AWS 構成図を書く際、省略してしまうことが多いサービスについて思いを馳せました。 よくある?構成図 リージョン アベイラビリティゾーン ルートテーブル AWS IAM インスタンスプロファイル Amazon EBS Elastic IP Elastic network interface(ENI) セキュリティグループ セッションマネージャーする時のエンドポイント 最終構成図 終わりに よくある?構成図 よくあると思われる構成図を描いてみました。 AWS になじみがある方から見ると、 「ふむ、パブリックサブネットとプライベートサブネットに 1 台ずつ EC2 インスタンスがあって、プライベートサブネットのインスタンスにはセッションマネージャーでログインするのかな?S3 バケットもあるな」 くらいの想像ができるかもしれません。 リージョン
Google 認定トレーナー/イーディーエル株式会社代表取締役 「Google 認定トレーナー」および「Google Cloud Partner Specialization Education」の2つを保有する国内唯一の女性トレーナー経営者。 数時間でITスキルを劇的に引き上げる指導に定評があり、ITビギナーから絶大な信頼を得ている。早稲田大学第一文学部(教育学専修)卒。筑波大学大学院教育研究科修了(教育学修士)。筑波大学大学院非常勤講師。アルマ・クリエイション株式会社主催「クロスセクター・リーダーズサミット」2年連続最優秀MVP(2019年、2020年)。常陽銀行主催第3回常陽ビジネスアワード「ウーマノミクス賞」379プラン中第2位(2015年)。出版社勤務を経て専業主婦になるも、学習欲が高じて大学院に進学。在学中に事業欲が高まり、IT教育会社を起業し、現在に至る。「日本に最高のIT
M1Mac × Docker × SchemaSpy × MySQL8.0でテーブル定義書とER図を自動生成してみる 2022.10.19 技術 Docker, MYSQL こんにちは、システム部の能勢です。昨年の秋に入社して、今はバックエンドを中心に開発を担当しています。 「この設計資料、最終更新何年前やねん」 「なんか現実と違うんですけど」 こんな言葉にビビビっとくる方いませんか? 最近はかなり激減したんですが、自分は少なくともエンジニアキャリアの最初の方ではこういう経験をよくしてきたタイプです。 弊社みたいにプロジェクトリリース前にドキュメントを第三者視点できっちり確認されるような体制のある開発現場ではこういうことが起こるのも低頻度だと思うんですが、実際問題世の中にはいろんなタイプの現場がありますし、そこまできっちり管理しきれない・・・こんなホンネが漏れるのが実情という方も多いんじゃ
下記ドキュメントバージョンに関する注意点です。 バージョン番号のルールを定める:バージョン番号は、どのようにつけるかルールを定め、チーム全員が同じ理解で使用するようにする必要があります。たとえば、変更内容によって数字がどのように増えるか(major, minor, patch)、何桁で表現するかなど、具体的に決めておくことが重要です。 変更履歴を明確にする:どのような変更があったのか、それがどのバージョンで実施されたのかを明確にすることが必要です。これにより、何らかの問題が発生した場合に、どのバージョンから問題があるのか特定することができます。 ドキュメントの保存場所を一元化する:ドキュメントのバージョン管理には、ドキュメントを保存する場所を一元化することが重要です。それにより、異なるバージョンのドキュメントが、複数の場所に分散してしまい、誤ったバージョンが使用されることを防ぐことができま
みなさん、コードを書く前に設計書を書きますか? 書くか書かないかは人それぞれだと思いますが、「設計」というプロセス自体は意識的であれ無意識的であれエンジニアであれば全員やっていることだと思います。 今回は設計プロセスの改善という文脈で私たちがDesign Docという仕組みを導入したことについて共有しようと思います。もし同じような状況を経験している人がいたら参考になれば幸いです。 導入の背景まずは導入するに至った状況からお話します。 私たちのサービスは、利用していただくユーザーの数が増加しています。それに伴って品質のハードルも上がってきました。サービスに障害が発生するとユーザーさんに大きな損害を出してしまうことになるからです。そこで今まで以上に安全にサービスを開発できる仕組みづくりが必要になりました。ですが、実現のためには大きく2つの課題がありました。 課題1. 開発スピードが徐々に鈍化し
howto-tech-docs.md 技術文書の書き方 このメモは、私(@ymmt2005)が長年にわたってソフトウェアプロダクト開発に関わってきて 2022年現在こうしたほうが良いと考えているベストプラクティスです。 科学的な分析等に基づくわけではない経験則であるため、今後も随時見直すことがありますし、 ここに書いてあることが常に正しいわけでもあらゆるソフトウェア開発に適するわけでもありません。 しかしながら、実務経験が豊富で、モダンな技術スタックに明るいエンジニアの経験則は一定の 役に立つのではないかと考えて記します。 技術文書とは ここでは、ソフトウェア開発で技術者が書くべき文書ということにします。 ソフトウェアエンジニアにも役割がいろいろあり、アーキテクトと independent contributor では書く文書が違うということはあるでしょうけれど、ここではごっちゃにします。
Diagram as Code6 different ways to turn code into beautiful architecture diagrams
概要 Design Documentと聞くと何を想像しますか? 一般的にDesign Documentが指すのは設計書であることが多いのではないでしょうか。 設計書、簡単に説明するのであればソフトウェアを「どうやって作るの?」を説明したドキュメントです。 Googleではソフトウェアエンジニアリング文化における重要な要素として、今回お話ししていくDesign Docsと呼ばれるものがあります。 Design Docsとは? Design Docsとは、開発者がコーディングに着手する前にソフトウェアシステムまたはアプリケーションの開発する人が作成するドキュメントです。 => ソフトウェア設計における仕様書や設計書とは別物と捉えた方がよいです。 仕様書、設計書は作成した上でのDesign Docsの作成となるようです。 このドキュメントには、高レベルの実装戦略と主な設計の決定事項がまとめられて
こんにちは、CX事業本部 IoT事業部の若槻です。 Draw.io(diagrams.net)は、JGraph Ltdにより提供されているオンラインのダイアグラム作成サービスです。無料で利用可能です。 Diagram Software and Flowchart Maker 今回は、Draw.io(diagrams.net)で作成したインフラ構成図をコードで管理し、GitHubで編集差分を見る方法を確認してみました。 やってみた VS Codeプラグインの導入 Draw.ioの構成図のデータは、Draw.io Integrationというプラグインを使えばVisual Studio Codeで編集できます。とても便利なプラグインなので導入します。 Draw.io Integration - Visual Studio Marketplace Draw.ioで構成図を作成する Draw.io
Googleでの「Design Docs」とは 2007年の Google Developer Day Tokyo での鵜飼氏のプレゼンによると「Google で必ず書くことになっているドキュメント」であり、「プロジェクト立ち上げ時の 1~2週間をかけて書く」ものです。 今回は Google のソフトウェアエンジニアである @cramforce 氏が自身のブログで「Googleでの Design Docs」について解説している記事を公開されていたため、氏の許可を得て翻訳しています。 原文: www.industrialempathy.com 関連書籍: Googleのソフトウェアエンジニアリング ―持続可能なプログラミングを支える技術、文化、プロセス オライリージャパンAmazon 読了目安:11分 (目次) デザインドキュメント の解剖学 文脈と範囲 目標と非目標 実際のデザイン システ
本書『サバイバルTypeScript』は実務でTypeScriptを使う開発者のための入門書です。そして、このページはTypeScriptの特徴を最速で把握できるよう、数百ページからなる本書のコンテンツをつまみ食いした要約です。 » 本書ついて詳しく知る » とにかく今すぐTypeScriptを書いてみたい TypeScriptとはJavaScriptのスーパーセットとなるプログラミング言語。静的型付け言語であり、プログラムの正しさが静的に検査できる。ライブラリやIDEなどの開発環境が充実しており、大きなエコシステムを持っている。Microsoftが2012年に開発し、オープンソースで公開した。» TypeScriptの特徴について詳しく知る » TypeScript誕生の背景について詳しく知る TypeScriptはJavaScriptのスーパーセットスーパーセットとは、元の言語との
こんにちは丸山@h13i32maruです。つい先日、devchat.fmというポッドキャストに出演して、「ドキュメント」というお題について話しました。なぜこんなニッチなお題について話したかというと、Ubie Discoveryに入社して5ヶ月の間にいくつか*1まとまったソフトウェアドキュメントを書いたので、自分の中でホットな話題だったからです。 #devchatfm 33回目は、Ubie DiscoveryのSWE @h13i32maru にドキュメントを書くことで得られるメリットや、ポイント・工夫などを聞きました! #33 チームの生産性を上げるドキュメントのすすめ with@h13i32maruhttps://t.co/TrmZd13D91— 久保 恒太 / Ubie CEO (@quvo_ubie) 2021年8月12日 これらのドキュメントは個人的にわりと良く書けたと思ってますし、
「公式ドキュメントを読め」というのが急に話題になっていたので自分なりに整理してみました。 注意: そんなに真面目に推敲していません。フィーリングで書いているので実態に即してない部分もあるかも…… 公式ドキュメントとは何か あなたが使おうとしている道具 (ライブラリ、フレームワーク、プログラミング言語、ミドルウェア、コマンドラインツール、etc.)[1] は必ず誰かによって作られています。ある程度成熟した道具であれば通常、その作った人・組織自身によって公開されているドキュメントがあるはずです。これが公式ドキュメントです。 公式ドキュメントは、OSSにおいてはソースコードと双璧をなす最も信頼できる資料のひとつです。ソースコードが非公開の場合は通常、公式ドキュメントが最も信頼できる資料でしょう。 (以降はOSSを主に想定して説明します) たとえば…… Python のソースコードはGitHub上
コーディングを勉強している方や、普段当たり前のようにコーディングしているけれど、上手く使えているのか不安な方向けにGoogle HTML/CSS Guideの翻訳記事を書きました。(2024年02月29日更新) 色んな方のコーディングを見ていると実に様々。情報や知識が古いままで、今では推奨されない書き方も散見されます。 特に仕事で使っていると、誰かに指摘されない限り自分のコーディングを見直す事は無いかもしれません。 ですがW3Cの定めたHTML5の廃止など、変化の速い業界では定期的な見直しは勿論、何か指標となる物があると安心です。 そこで今回はGoogleが用意しているgoogle html/css style guideのドキュメントを元に、Googleコーディング規約と要点を解説。このコーディングガイドラインが絶対的な正解では無いかも知れませんが、参考になれば嬉しいです。 Google
開発プロジェクトに新しく加わった時は、まずプロジェクトの理解が第一。しかし、全体像を把握できるようなドキュメントがなく、コードから断片的な情報をかき集めるしかない場合もあります。新参の開発者がスムーズにプロジェクトを理解できるよう、大規模なプロジェクトでは「プロジェクト全体のアーキテクチャ」を示した「ARCHITECTURE.md」を添えた方がよいと、エンジニアのAleksey Kladov氏が指摘しています。 ARCHITECTURE.md https://matklad.github.io//2021/02/06/ARCHITECTURE.md.html Kladov氏はオープンソースプロジェクトの開発に携わる中で、「プロジェクトのアーキテクチャに対する知識量」によって開発スピードに大きな差が生じると気づいたとのこと。アーキテクチャに関する知識がない開発者にとって、大量のコードは「バラ
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
処理を実行中です
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く