Markdown タグ

Goならわかるシステムプログラミングなどのウェブ連載や書籍化でお世話になりまくりの鹿野さんのブログ記事が話題となっています。これを読んで、今までモヤモヤ思っていたことに光明が射してきたので、ちょっと実験してみました。

Markdownでプロジェクトの進捗報告やチームの振り返り資料をまとめていると、「ここにグラフがあれば一目で伝わるのに」という場面に出くわします。Mermaid.jsでグラフ化するとAIとの連携も便利でした。

2024年9月18日に発売された、Software Design 2024年10月号の第1特集「再考 設計ドキュメントの課題　二重管理しない，陳腐化させない」の「第1章：受託開発における設計ドキュメントの課題と解決案　作成・管理のヒントを探る」に寄稿させていただきました。

生成AIが人気です。生成AIに対しては自然言語で指示を与えられますが、自然言語を構造化してやりとりする方法としてはよくMarkdownが使われます。その生成AIフレンドリーなMarkdownで設計ドキュメントを作るとしても...

Findyさん主催のドキュメント管理を制する 陳腐化を防ぐための実践事例 Lunch LTに「設計ドキュメント腐る問題、Git管理で運用してみた本当のところ」というタイトルで登壇しました

Markdownで設計書を充実させようとすればするほど、設計書間やメンバー間のちょっとした揺れで、本質的なレビューがしにくく感じるようになりました。そこでMarkdownのLintツールを導入するモチベーションが高まりました。

お客様と一緒にNext.jsのドキュメントの輪読会をやっているのですが、その中で初めて知った機能がMDXというマークダウンでページを作成する機能です。https://nextjs.org/docs/advanced-features/using-mdx利用規約とか、プライバシーポリシーのページ、ヘルプページの作成とか、Reactコンポーネントも表示できるので、Storybookがわりのコンポーネントカタログを作るのに便利そうという話になったので、ちょっと試してみました。

私のチームでは、「システムの設計情報」や「実装に関わる業務知識」などを、README.md に整理して GitHub 管理しています。設計資料や業務系のドキュメントが蓄積され、何度も更新され続けることに伴い、「あれ、この資料のリンクが切れてる。オリジナルのファイルはどこだっけ？」と探す機会が増えてきました。本来ならば PullRequest のレビュー時に気付くべきですが、ファイル名のちょっとしたスペルミスや資料パスの変更などだと、目視でのチェックには限界があります。

皆さん、Marpはご存じでしょうか？Marpとは、Markdown記述形式でスライドを作成するができるツールです。VSCodeにインストールことで、VSCode上でスライドの作成を行うことができるようになります。まさにあったらいいなが具現化したようなツールです。もちろん、Marpから作成されたスライドはパワポでの再編集も可能で、骨子づくりはMarp、仕上げはパワポ、なんて合わせ技も行えます。今回はそんなMarpを業務でも平常利用できる状態に持っていくべく、スライドのテンプレートの仕込みをやってみたいと思います。