Update 2025/5/6
Jan 2025 The Symbol Syndicate’s Docs Blogs
2025年1月のブログはこちらから
【日本語訳】ドキュメントの現状についての評価
- このトピック別のサイト構成は読者にとって少々不親切であり、必要とする情報に辿り着くことを難しくしています。
- ガイドの中には、長い間プレースホルダー状態のままで内容が追加されていない箇所もあり、内容が薄いものがあります。
- 最上位のセクション項目が6つありますが、数が多く、どこに該当するかの判断材料となる情報も少ないため、非常に分かりにくいです。また、左側のメニューとも一致していません。
- 上部のナビゲーションバーと左のメニューが一致していないため、構成を分かりにくくしており、SDKなどのページは非常に見つけにくい場所にあります。また、ハンドブックのページは、本来ならば誰にでも見られるように公開すべき内容です。
- 一部のセクションは、Python SDKのような古い情報だったり、すでに非推奨となっている旧バージョンのJS SDKやJava SDKのようなものもあります。
これらの理由から、ほとんどのページで書き直しが必要となるため、全く新しいサイトを作成することを提案しました。
新サイトの提案
- 対象とする読者に応じた3つのセクション構成:
- ユーザーガイド: コードを必要としない操作方法（ウォレットの使い方など）
- 開発者向けガイド: コードを使ってさまざまなアクションを実行する方法（チュートリアル）
- テキストブック: 技術的背景などの解説
- いくつかの追加項目:
- 読者が略語の意味を調べるためにページを離れなくても済むよう、用語集がツールチップ（小さなポップアップ）として表示される機能を用意する。
- CIパイプラインで検証済みの様々なプログラミング言語のシンタックスハイライト付きコード例を表示する。
- APIおよびSDKのリファレンスドキュメントを埋め込み、別サイトを閲覧しているような印象を与えないようにする。チュートリアルからは特定のメソッドやクラスへリンクでき、それらの説明をツールチップでも表示できるようにすることが望ましい。
- ライトモード及びダークモードのサポート。
- スモールスクリーン（モバイル）のサポート
- 多言語対応 (少なくとも日本語には）。
これらは 私が実装したいと考えている 機能です。すべてを実装できるというお約束はここではできませんが、それらの実現に向けて最善を尽くすつもりです。
これまでの作業
まず始めに、様々なドキュメンテーションフレームワークを検討しました。既存のドキュメントではSphinxを使っており、これはこれでとても気に入っていたのですが、GitBookやDocusaurusのような他の選択肢についてもさらに調査してみました。そして最終的には、MaterialテーマとMkDocsの組み合わせに落ち着きました。これは私が得意としている組み合わせで、実装したいと考えている機能を満たせると考えたからです。その上、テーマ、スモールスクリーン（モバイル）、多言語化対応などのサポートが標準で備わっている点も決め手となりました。
次に、新しいMkDocsプロジェクトを作成し、初期のページ構成を整え、残りの必要な機能を実現するためにプラグインの追加を始めました:
- ezglossary: 用語集だけでなく、ドキュメントリファレンスにも対応するツールチップに使用します。
- mkdocstrings: ソースコードから直接APIドキュメントを生成します。 mkdocstrings-python、 mkdocstrings-typescript及びJava対応の mkdoxy と組み合わせて使用します。
- 更にいくつかの補助プラグインとして meta-manager、 gen-files、 literate-nav、 git-authors等を使用します。
試してみたプラグインの中には、すぐにそのまま使えるものもあれば、プラグイン同士が競合してしまうものもあり、また開発中のものもありましたので、うまく機能する組み合わせを見つけるには色々と試行錯誤が必要でした。
現在、自動生成されたドキュメントの一部の修正に手間取っており、また、サイトの見栄えを良くするための画像をデザイン担当から届くのを待っている状況です。これらが整い次第、新しいサイトの動作確認版（PoC）を共有できる見込みです。 🙂
次の作業
ツールが私のやりたいことをすべてサポートしてくれると確信でき次第、追加すべきすべてのページの詳細なタスクリストを作成し、おそらくライターを雇い、執筆を開始します！
さて、現場に戻りましょう！ご意見やフィードバックがございましたら、お気軽にお知らせください。ではまた来月！
—