設計ドキュメント腐る問題、Git管理で運用してみた結果 | フューチャー技術ブログ
はじめにTIG真野です。 秋のブログ週間2023 の3本目は、設計ドキュメントをGit管理して腐らせないようにがんばってみた話をします。 前段として6年前、「我々はいかにシステム開発におけるドキュメント腐る問題と戦えば良いのか」という記事を書いたのですが、その後の試行錯誤はどこにも残していないことに気づきました。普段のフューチャー技術ブログですとちょっと引け目を感じるテーマですが、秋の夜長を楽しむため読み物成分を多めに書くというテーマのこのブログリレーにピッタリな気がするため、この機会をお借りします。 ドキュメントも色々な種別があるかと思いますが、この記事では設計ドキュメントを指すことにします。設計ドキュメントは開発メンバーが参照するもので、ステークホルダーへの説明資料に引用して使うことはあれど、主目的は異なるという前提です。Design Docの場合もありますし、システム構成図、ERD、
markdownlintで設計書の品質を高める | フューチャー技術ブログ
はじめにフューチャー技術ブログのリレー形式の連載である、春の入門祭り2023の1日目です。TIG真野です。 ここ数年、Markdownで設計書をチームで書き、GitHub（GitLab）上でレビューするフローを採用しています。なるべくテキストベースで設計開発フローを統一するため、私の所属するチームでは以下のようなツールを採用しています。 シーケンス図、業務フロー図 Markdown中にPlantUMLで記載 参照はGitHub上からも見れるように、pegmatite を利用 システム構成図など画像系 Diagrams.net（draw.io）で作成し、.drawio.png の拡張子でMarkdownから参照 これだけは目視で差分チェックとなる Web API定義 OpenAPI SpecのYAMLファイル 参照はGitHub上からも見れるように、swagger-viewer を利用 ER
一度使うと資料作成が楽になるマークダウン記法 | Sqripts
こんにちは！とりです。 実は私、Sqripts記事の推進も担当しているんですが、記事を書く際にもよく使われる記法としてマークダウン（Markdown）記法というものがあります。エンジニアやソフトウェア開発に携わる人がドキュメントを書く際にもよく利用され便利な記法で、ソフトウェアテストと直接関係するテーマではありませんが、利用できるシーンも多いため、まだ触れた事がない方向けに記法書式や実際に使用した所感を交えて紹介したいと思います。 マークダウン記法とは？ ウェブページのファイルに使用されているHTMLは、世間一般的にも有名な記法ですが、それを更にシンプルかつ、楽に書ける様にした記法です。元々は、マークアップ（Markup）と呼ばれる、文章にタグなどの形で文章構造（書式など）を明示するための言語があり（代表的な言語としてHTML）、そのマークアップを簡略軽量化したものがマークダウン記法です。
Architectural Decision Records | adr.github.io
Architectural Decision Records (ADRs) An Architectural Decision (AD) is a justified design choice that addresses a functional or non-functional requirement that is architecturally significant. An Architecturally Significant Requirement (ASR) is a requirement that has a measurable effect on the architecture and quality of a software and/or hardware system. An Architectural Decision Record (ADR) cap
グラフを生成可能なマークダウン構文「Mermaid」がNotionで利用出来るようになりました #notion | DevelopersIO
データアナリティクス事業本部 サービスソリューション部 サービス開発チームのしんやです。 Notionの直近リリースノートに「Mermaidっていうマークダウン構文がNotionで使えるようになったよ！」という情報が載っていたので、試してみた内容を軽くではありますが紹介したいと思います。 目次 Mermaidとは 実践 #1. フローチャート #2. シーケンス図 #3. クラス図 #4. 状態遷移図 #5. ER図 #6. ジャーニーマップ #7. ガントチャート #8. パイチャート #9. 要件図 まとめ Mermaidとは Mermaidとは、フローチャート、シーケンス図、クラス図、ガントチャート、およびgitグラフを生成するためのマークダウン構文です。 コードから良い感じのグラフを生成できるイメージについては下記動画を参照頂くと良さそうです。 実践 では早速実践してみたいと思いま
よくあるAWSサーバーレス構成のシーケンス図をMarkdown（Mermaid）で描いてみた | DevelopersIO
こんにちは、CX事業本部 IoT事業部の若槻です。 今までシステムのドキュメントなどでUML図を使用したい場合は、別途PlantUMLで書いて画像ファイルを生成し、MarkdownやAsciiDoc内に配置するということをしていました。 しかしこちらの記事の通り、Mermaidを使用すればMarkdown内で直接UML図の定義をコードで記述し、さらにGitHub上ではそのまま描画までしてくれるとのことです。知らなかった…！ GitHubでmermaid記法が使えるようになったのでアーキテクチャーの図を書いてみた | DevelopersIO そこで今回は、下記のようなよくあるAWSサーバーレス構成（API Gateway + Lambda + DynamoDB + α）のシーケンス図をMermaidで描いてみました。 描いてみた Mermaidにおけるシーケンス図の文法はこちらを参考にしま
Visual Studio Code で UML を描こう！ - Qiita
この記事では、Windows 環境に Visual Studio Code と PlantUML をセットアップする手順を説明します。 PlantUML とは PlantUML は、以下のような図をテキストで素早く描くためのオープンソースプロジェクトです。 シーケンス図 / Sequence diagram ユースケース図 / Usecase diagram クラス図 / Class diagram アクティビティ図 / Activity diagram コンポーネント図 / Component diagram 状態遷移図 / State diagram オブジェクト図 / Object diagram 環境 下記の環境で動作確認しました。 Windows 10 Pro (64bit) Visual Studio Code 1.11 Java SE Runtime Environment
Markdown の見出しに章番号を振る方法(ついでに目次にも) - Qiita
はじめに Markdown でちょっとしたメモを書いていると、メモ書きのつもりが、それなりの規模になってきて、目次を作りたくなる。目次をつけるのは Markdown Preview Enhanced の機能でできる。 そんで、目次をつけると、どうも章番号を振りたくなってくる。 章番号を振る一番単純なやり方は、見出しに対して手でぽちぽち番号を振っていく方法だけれども、文章の更新がかかるたびに番号を振りなおすのはいかにも効率が悪い。 というわけで Markdown Preview Enhanced のスタイルを使って、見出しに対して自動的に章番号を割り付けるようにしたので、その方法をまとめておく( Markdown Preview Enhanced とは書いているけど、同様に CSS で見た目をコントロールしているよう他のプレビュー機能でも有効な方法のはず)。 ついでに、同様の方法で目次にも番
PlantUMLサーバをDockerで1分でサクッと構築＋VSCodeでプレビューする | SyachikuLOG
みなさん、システムのドキュメント作成に疲弊してませんか？ 私はいままで画面遷移図やワークフロー図などのシステムドキュメントはVisioやExcelで作っていました。ただVisioやExcelの場合にはシステムがある程度の大きさになってくると矢印が変なとこにくっついたり、配置が崩れたり（涙）結局、図面を作成するだけで時間がかかってしまう・・・そんな経験ありますよね・・・ そんな時、「PlantUML」というツールを使ってみたところ非常に簡単に図面が作れてしまいました！これは本当にマジで最高です！近年の中で一番オススメできるツールです！そこで今回はPlantUMLをDocker上にサクッと構築する方法をご紹介したいと思います。Dockerの環境があればさくっと5分以内で構築できます！ また、VSCodeのPlantUMLの拡張機能を追加することでリアルタイムで図面をプレビューする方法やMark
ドキュメントベースの型安全なモバイルアプリ行動ログ基盤の構築 - クックパッド開発者ブログ
こんにちは。PlayStation 5が一向に買えない@giginetです。普段はモバイル基盤部というところでiOSの基盤開発をしています。 皆さん、行動していますか？我々は日々Webサービス上で様々な行動をしています。サービス開発において、改善に活かすための効率的な行動ログの収集方法はしばしば課題になります。 今回は、サービス開発者がモバイルアプリ上で簡単にログを定義し、分析を行えるログ基盤を導入した事例について紹介します。 行動ログとは何か モバイルアプリの行動ログとは、ユーザーのアプリ上の操作や利用状況を取得、集積するためのものです。 例えば、特定の画面を表示したり、特定のボタンをタップしたり、といったユーザー操作を起点として送信されています。 集められたログは、サービス開発のための分析や実態把握に役立てられます。 最近はFirebase Analyticsなど、PaaSの形態で提供
Visual Studio Codeで作るLT資料 〜 脱パワーポイント - Qiita
はじめに SoftwareDesign 11月号のVisual Studio Code快適生活という記事の中で、VS Codeでプレゼンテーションを考えてみるという話があり、面白そうだったので試してみました。 LT資料をサクッと作ってしまいたい、発表時にはソースコードを交えながら話したいという思いを実現します。 ※個人ブログを開設したことを契機に、記事を移植しました。 こちらから御覧ください。
GitBookを使ってみる - Qiita
※ブログ記事のコピーです。 とあるサービスのドキュメントを拝見した際に「Published with GitBook」と書いてあって「GitBookとはなんぞや？」となったので調べてみました。 GitBook どうやら「Markdownの書式で書いたドキュメントをイイ感じにHTML(Webで閲覧するためのドキュメント)に変換してくれる」ツールのようです。 文章量が多くなってしまったKiribi UsusamaのREADME.mdを分割・整理するのにちょうど良さそうな感じでしたので、試してみました。 1. GitBookインストール まずはインストールです。Node.jsが直かnかnvmかnodist辺りでインストールされていることを前提として、ドキュメントを作成したいディレクトリまで移動します。 その後、そのディレクトリ下にてnpmでGitBook(gitbook-cli)をインストールし
AWS SDKを使ってSecurity GroupをMarkdownのテーブルで出力するスクリプトを書いてみた | DevelopersIO
最近寝違えたせいで、首を斜めに傾けながら仕事をしているもこ@札幌オフィスです。 めちゃめちゃ量があるSecurity GroupをMarkdownのテーブルでまとめてドキュメント化したかったので、Node.js + AWS SDKを利用して、Markdownのテーブルで出力するものを作ってみました 作ったもの アカウントにあるSecurity Groupを引っ張ってきて、IngressをMarkdownで出力します。 同じポートで複数のソースがある場合は、<br>を挟んでいい感じに改行するようにしています 使い方 GitHubに上げていますので、Cloneしてpackageをインストールして実行です！ git clone https://github.com/mokocm/sg-markdown cd sg-markdown npm i node index.js コード describe
会議を爆速にする、Visual Studio Code 超便利スニペット集 - Qiita
以前の投稿でVisual Studio CodeとMarkdown Preview Enhanced環境を組み合わせの便利さを紹介しました。 議事メモを作成にマークダウンを使うと、議論が構造化されて表示されるので、非常にわかりやすくなりますね。みなさんもお使いかと思います。本稿では、そこに、更にVisual Studio Codeにマークダウン用のスニペットを登録しておくことを提案します。 出席者の議論をフォーカスさせる図や表がスムーズに呼び出せますので、効率的な会議を行うことができます。そんな爆速会議に便利なスニペットをいくつか紹介します。 以下ではVisual Studio CodeエディタとMarkdown Preview Enhancedプラグインが前提となっております。環境構築には以前の投稿をご参照ください。 1.会議を一気に立ち上げる：議事録スニペット まずは議事録のテンプレー
Visual Studio Code + MarkDown + PlantUML で開発ドキュメントをわかりやすくする - Qiita
きっかけ githubなどのソース管理ツールで新規のリポジトリを作成したり、フレームワークのプロジェクトを作成したりすると、Readme.mdができる。 Markdownは流行りというか、Qiitaでもお馴染みだし使いやすい。 しかし、画像（というか図）はどこかで作ってリンクするなど、ちょっと面倒だった。 そんな中、こんな記事を見る。 https://qiita.com/kitfactory/items/31cdf80cf1d3d8b42de8 「ああ、Markdownで図が描ける」 ということで、さっそく導入しようとしたのだが、最初の？？？となったところをまとめておく。 導入手順 Windows環境にVSCodeは既にインストール済みであることは前提として、次の手順が必要となる。 VSCodeの拡張機能で、「Markdown Preview Enhanced」をインストール 以下URLか
Visual Studio Code + Markdown Preview Enhancedはチームでデファクト化したいMarkdown環境だ！、と思う�(2017/10月時点) - Qiita
Visual Studio Code + Markdown Preview Enhancedはチームでデファクト化したいMarkdown環境だ！、と思う�(2017/10月時点)MarkdownエディタVSCodeVisualStudioCode 0.注意書き 筆者の本稿での意図はエディタ宗教論争を巻き起こすことではありません。「世の中では、これくらいのことが出来るようになってきている」とご参考にしてただくことが本稿の狙いです。それによって何かのお役に立てれば幸いだなと思っています。 皆さんは自分の使いやすい、皆さんの用途やプロジェクトの環境をにあったエディタを使用していただければとお断りしておきます。 1.Markdown環境について Markdwonは以前に書いたように今後の文書生産性を変えていく可能性のあるツールの一つです。Markdownのメリットは次の点だと思います。 1.1.M
MarkdownとPlantUMLでソフトウェアの仕様書や設計書を書くための環境構築手順 - EurekaMoments
実践UML 第3版 オブジェクト指向分析設計と反復型開発入門 作者:クレーグ・ラーマンピアソンエデュケーションAmazon 目次 目次 はじめ Markdownで書くメリット Markdown記法一覧 環境構築手順 1. Visual Studio Codeをインストールする 2. PlantUMLをインストールする 3. Javaをインストールする 4. Graphvizをインストールする 5. Markdown Preview Enhancedをインストールする 環境構築後の動作確認 Markdownでドキュメントを書く際に便利な拡張機能 1. Paste Image 2. markdown-index 作成したドキュメントをHTMLやPDFに変換する 今回参考にさせていただいた記事 はじめ 自分はこれまでソフトウェア開発において仕様書や設計書を作成する際、Enterprise Arc
[Markdown] Markdown でシーケンス図を書いてHTMLに出力しよう - Qiita
私事であるが、Visual Studio Code をメインエディタとして使用している。 で、資料を作る際にシーケンス図をパパッと書きたい、といったときに便利なツールとして mermaid.js があるということを知ったので、私なりの導入や利用方法について備忘録がてら記事にしたい。 前提 シーケンス図を描きたいが UML モデリングツールを使うのは面倒だ Visual Studio Code を使用している Visual Studio Code からシーケンス図が書けたら幸せだなぁという願望がある そしてそのシーケンス図をHTMLドキュメントに出力できたら嬉しい で、本記事の趣旨は Markdown でシーケンス図を書こう｡ そしてそれを HTMLドキュメントに出力しよう ということなので、そのためのアレコレを以下に記していく。 mermaid.js を使おう 冒頭で触れた mermaid
![[Markdown] Markdown でシーケンス図を書いてHTMLに出力しよう - Qiita](https://cdn-ak-scissors.b.st-hatena.com/image/square/36bb97f6057a21c26b08021cb4438472cf670ddb/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-412672c5f0600ab9a64263b751f1bc81.png%3Fixlib%3Drb-4.0.0%26w%3D1200%26mark64%3DaHR0cHM6Ly9xaWl0YS11c2VyLWNvbnRlbnRzLmltZ2l4Lm5ldC9-dGV4dD9peGxpYj1yYi00LjAuMCZ3PTk3MiZoPTM3OCZ0eHQ9JTVCTWFya2Rvd24lNUQlMjBNYXJrZG93biUyMCVFMyU4MSVBNyVFMyU4MiVCNyVFMyU4MyVCQyVFMyU4MiVCMSVFMyU4MyVCMyVFMyU4MiVCOSVFNSU5QiVCMyVFMyU4MiU5MiVFNiU5QiVCOCVFMyU4MSU4NCVFMyU4MSVBNkhUTUwlRTMlODElQUIlRTUlODclQkElRTUlOEElOUIlRTMlODElOTclRTMlODIlODglRTMlODElODYmdHh0LWFsaWduPWxlZnQlMkN0b3AmdHh0LWNvbG9yPSUyMzIxMjEyMSZ0eHQtZm9udD1IaXJhZ2lubyUyMFNhbnMlMjBXNiZ0eHQtc2l6ZT01NiZzPTQyMTlkMzQxZGMyNjcwNTcwNDhjZjE3ZTQxMzI0YzAz%26mark-x%3D142%26mark-y%3D57%26blend64%3DaHR0cHM6Ly9xaWl0YS11c2VyLWNvbnRlbnRzLmltZ2l4Lm5ldC9-dGV4dD9peGxpYj1yYi00LjAuMCZoPTc2Jnc9NzcwJnR4dD0lNDBrc2gtZnRociZ0eHQtY29sb3I9JTIzMjEyMTIxJnR4dC1mb250PUhpcmFnaW5vJTIwU2FucyUyMFc2JnR4dC1zaXplPTM2JnR4dC1hbGlnbj1sZWZ0JTJDdG9wJnM9NWNiYmU4YzBkNjRjZGNhMDdjM2NmOWE0Y2I3MDQ3ZTY%26blend-x%3D142%26blend-y%3D486%26blend-mode%3Dnormal%26s%3D15c3df6c4103c400853d71f2d353b44b)
Markdown記法 チートシート
Markdown記法のチートシートです。 記法はGitHub Flavored Markdownに準拠し、一部拡張しています。 Qiitaでシンタックスハイライト可能な言語一覧については、 シンタックスハイライト可能な言語 をご覧下さい。 Code - コードの挿入 Code blocks - コードブロック たとえば、「Ruby」で記述したコードをファイル名「qiita.rb」として投稿したいときは、 バッククオート（`） か チルダ（~） を使用して以下のように投稿するとシンタックスハイライトが適用されます。 コードブロック内でコードブロックを書きたい場合は異なる記号を使うことで書けます。
【環境構築10分】Markdown形式（md）のドキュメントを Word 形式（docx）に変換する | DevelopersIO
Markdownで書きたいけど、Wordで提出したい Markdownは簡単かつシンプルに記述ができて便利ですよね。しかしながらMarkdownは非エンジニアのかたに共有するドキュメントとしてはハードルが高いので適しません。 そこでWordなどで読めるようにする必要が出てきますが、変換作業が必要になります。 Markdown形式からWord形式（docx）に変換するにはPandocというツールが便利ですが、環境構築が面倒としう課題がありました。 しかし現代ではDockerという素晴らしいプラットフォームがある。ということですごく簡単に実現ができたので、記事としてまとめたいと思います。 検証環境 macOS High Sierra 10.13.2 Docker Version 18.06.1-ce-mac73 (26764) Docker for Macのインストール 最低限、Docker
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
