はじめにTIG真野です。 秋のブログ週間2023 の3本目は、設計ドキュメントをGit管理して腐らせないようにがんばってみた話をします。 前段として6年前、「我々はいかにシステム開発におけるドキュメント腐る問題と戦えば良いのか」という記事を書いたのですが、その後の試行錯誤はどこにも残していないことに気づきました。普段のフューチャー技術ブログですとちょっと引け目を感じるテーマですが、秋の夜長を楽しむため読み物成分を多めに書くというテーマのこのブログリレーにピッタリな気がするため、この機会をお借りします。 ドキュメントも色々な種別があるかと思いますが、この記事では設計ドキュメントを指すことにします。設計ドキュメントは開発メンバーが参照するもので、ステークホルダーへの説明資料に引用して使うことはあれど、主目的は異なるという前提です。Design Docの場合もありますし、システム構成図、ERD、
VSCode上でシーケンス図/クラス図/フローチャートをサクッと書きたい ~Mermaid Graphical Editor~ - Qiita
VSCode上でシーケンス図/クラス図/フローチャートをサクッと書きたい ~Mermaid Graphical Editor~初心者umlVSCode新人プログラマ応援mermaid はじめに Mermaid Graphical EditorというVSCodeの拡張機能にとても感動したので一筆書きました こんな方におすすめ シーケンス図/クラス図/フローチャートをサクッと書きたいけどmermaidとか難しそう 😢 できること VSCode上でポチポチしながらシーケンス図/クラス図/フローチャートを描けるようになる mermaid記法のコードも自動生成されるよ 個人的メリット mermaidの学習コスト0 紙で書くよりも修正しながら書きやすい 導入手順 （簡単7steps） (1) VSCode上で「Mermaid Graphical Editor」という拡張機能をインストールする (2)
背景 開発チームが抱えるよくある課題として システムが変化する一方でドキュメントは更新されず腐る メンバーの流入出によって口伝でかろうじて継承された知見も失われる 検索性が良くないと過去のドキュメントが気づかれず、同じような内容のドキュメントが新規量産される 後から参加したメンバーはどちらが正のドキュメントか分からず混乱する といったことが良くあります。 解決方法としては以下のように、GitHub＆ルールベースで管理するといった例があります。 future-architect.github.io また組織・システムが大きくなってくると認知負荷を低減するためにドメインで区切るような形でチームの分割が始まりますが、 異なるチームによってシステムが管理され、システムの依存関係を全て知っている人がいなくなる CxOレイヤが大規模イベント前に現状を把握したいときに都度時間がかかってしまう チームごと
AIに仕事を奪われないために、自分の発想を強化していかないといけない 服部佑樹氏（以下、服部）：次に行きたいと思います。「エンジニアとAIの関わり方」ですね。AIが登場したことによって、どういうかたちでエンジニアが変わっていくのか。概念としてはものすごく広いですが、みなさんもいろいろな観点の捉え方があると思っています。 組織としてどうするのかはその次の質問になりますが、あとはキャリアとしてとか、次のポジションをどうしようかなみたいなところも含めて、個人の観点なども含めて答えてもらえるといいんじゃないかなと思います。では黒崎さんからいいですか？ （スライドを示して）3番目の質問「エンジニアがAIと協力して新たなアイデアを生み出すための効果的なアプローチ」ですね。あとは2番も合わせていいかもしれませんが、アプローチと潜在的な力を引き出すためのスキルをどうやって学んでいったらいいと思いますか？
背景: dbtを使っていてもER図は欲しい! どうやってER図を生成するか どうやってER図を見やすくするか まとめ 背景: dbtを使っていてもER図は欲しい! dbtはモデル間のリネージなど可視化が得意なツールではありますが、万能なわけではありません。モデルの生成過程などはリネージで担保できますが、分析時に「どれとどのモデルがJOINできて、JOINする際のキーはこれを使って」というER図で扱うような可視化はディフォルトではできません。 DWHを作っている側からすると「このテーブルはあの辺のテーブルと一緒に使うと便利で、いつもあのキーでJOINして」というのが頭の中に入っていることが多いため、ER図がなくてもどうにかなることも多いでしょう。しかし、分析に慣れていない人や分析に慣れている人であっても、普段と異なるドメインのテーブルを触るときはER図が提供してくれる情報は有用です。ちなみに
ドキュメント執筆にもGit、ビルド、テストで再利用性や整合性を実現する「Writerside」、JetBrainsがプレビューリリース
Kotlinなどの開発元として知られるJetBrainsは、テクニカルドキュメントのための一連のツールを統合したドキュメントオーサリングツール「Writerside」のプレビューリリースを発表しました。 ソフトウェア開発においては、テキストで記述されたソースコードをGitでバージョン管理し、ビルドによって複数のソースコードを1つのアプリケーションへとまとめ上げ、コンパイルし、テストをして本番環境へのデプロイによりアプリケーションを公開します。 そしてこのプロセス全体を、さまざまな機能を備えたツールチェンを用いて自動化することで、ソフトウェア開発の効率を高めています。 一方で、例えばアプリケーションのチュートリアル、SDKやAPIのリファレンスドキュメントなどのドキュメントの制作過程においては、複数のファイルをフォルダにまとめ、手作業で目次のページとリンクさせることや、ソースコードのサンプル
1. はじめに こんにちは、「信頼性は可用性ではない」を標語にしているnwiizoです。 近年、サービスの信頼性向上に向けた取り組みとして、SLI（Service Level Indicator）、SLO（Service Level Objective）、エラーバジェットという概念が注目を集めています。これらは、Google発祥のSRE（Site Reliability Engineering）プラクティスの中核をなす考え方であり、多くの組織がこのアプローチを採用し始めています。また、関連するツールも成熟し始めており、実践的な導入がより容易になってきています。 本ガイドでは、SLI、SLO、エラーバジェットを導入する前に知っておくべき重要なポイントについて詳細に解説します。各概念の定義から実践的な導入ステップ、さらには組織文化の変革まで、包括的な情報を提供します。 2. SREにおける基本
概要 本記事は、スクラムを管理するアプリケーションをクリーンアーキテクチャの考え方で実装し、WebからもCLIからも動かせるようにしたという実践を紹介するものです。学習のための個人開発で作成したサンプルアプリケーションの設計と実装を適宜紹介することで、クリーンアーキテクチャに対する理解を深めることが目的です。 モチベーション なぜ現代の開発現場で定着しているクリーンアーキテクチャのアプリを手元で実装してみようと思ったかというと、私自身Webエンジニアとして働く中で、クリーンアーキテクチャの実践例は入出力をWebに限定したものばかりだったからです。 しかし、「詳細に依存せず抽象に依存すること」と唱えるクリーンアーキテクチャにとって、Webはただの詳細です。そこで、入力元、出力先を問わないアプリケーションはどのような書き味になるのか、自分で確かめてみたくなりました。 例えば、「ドメイン層は独立
Mermaidが好きすぎるけど結局draw.ioにしがちな今日この頃ですが、ついにMermaidでAWSアーキテクチャ図が描けるようになったらしいので試してみました！ やってみた 感想としては、そこそこ複雑なものも描けそうです！ Mermaidのアーキテクチャドキュメントに飛んで、一番下のAWSアーキテクチャ図のサンプルコードに以下のコードをコピペして実行すると見ることができます mermaidコード architecture-beta service dns(logos:aws-route53)[Route53] service cdn(logos:aws-cloudfront)[CloudFront] service cert(logos:aws-certificate-manager)[ACM] service storage(logos:aws-s3)[S3] group vpc(
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
設計ドキュメント腐る問題、Git管理で運用してみた結果 | フューチャー技術ブログ
開発者ポータル Backstage とは - Carpe Diem
今後のスキルセットには必ず「AIを使いこなす」が組み込まれる GitHub CopilotとChatGPTの登場から考え直す、AIとの関わり方
dbtで見やすいER図を生成する - yasuhisa's blog
SLI、SLO、エラーバジェット導入の前に知っておきたいこと | sreake.com | 株式会社スリーシェイク
TypeScriptでクリーンアーキテクチャを実践する
MermaidでAWSアーキテクチャ図を描いてみた！