はじめに
こんにちは。ACS事業部 亀崎です。
以前、Backstageの基本機能である「Software Catalog」をご紹介しましたが、今回はそうした情報に関するドキュメントを共有する機能であるTechDocsをご紹介します。
TechDocs機能
PlaTT/Backstageの基本的なコンセプトは組織内における開発コンポーネント情報（および実行リソース情報）の共有財産化です。それぞれのチームが開発・利用するコンポーネントの情報をできる限り公開することで、チームのサイロ化・や重複開発を抑止しつつ必要な情報をチーム内およびチーム間で共有するものです。
以前ご紹介したようにどんなソフトウェア資産があるかという情報はSoftware Catalogで表現しますが、この他にもソフトウェアがどういったものか、使い方の紹介など、Markdown形式でドキュメントを用意することも多いかと思います。
TechDocsはこうしたMarkdownドキュメントを取得し、PlaTT/Backstage上でWebコンテンツ（HTML）化する機能になります。
画面表示
実際にどのような画面となるかを見ていただいたほうが早いと思いますので、さっそくご紹介します。
なお、実際に動いているものをご覧になりたい方は本家Backstageのデモサイトがありますのでそちらをご覧ください。
一覧表示
TechDocsがSoftware Catalogの機能拡張であるため、どんなドキュメントが登録されているかを一覧表示することができます。
コンテンツ表示
一覧から１つ選択すると、MarkdownドキュメントをHTML化したコンテンツが表示できます。
一覧以外での表示
TechDocsは一覧以外のところからも表示することができます。
まず最初にSoftware Catalog内のタブでの表示です。TechDocsはComponentやResource、TemplateといったSoftware Catalogに付属するものとして登録します。このためそれぞれのCatalog情報のタブ内でも表示ができるようになっていいます。
また、Template一覧の画面でもTechDocsへのリンクが表示されるため、すぐに詳細な情報を得ることができまｓ．
指定方法
では、実際どのように指定するかを見ていきたいと思います。 TechDocsを表示するためには２つの指定ファイルを用意します。
まずはCatalog情報そのものです。
TechDocsを有効化するにはcatalog情報に項目を指定します。以下の例はSoftware Templateのものですが、ComponentやResourceなどでも利用できます。
そしてもう１つがmkdocs.yaml です。こちらはTechDocsの目次といったドキュメントの付加情報を記述するものです。
まとめ
このようにSoftware Catalog情報やTemplateとともに、それらのドキュメントも一緒に表示できるため、チーム横断で設計情報を共有していくのに便利な仕掛けとなっています。
最後に
弊社では オープンソースのInternal Developer Portal であるBackstageをマネージド・サービスとして提供しています。
また、Platform Engineering、Backstageに関するご支援をさせていただいております。ご興味のある方ぜひご連絡ください。
