Skip to main content

ライブラリのドキュメントはどのように作成しようかなというのを調べました

· 3 min read

hosting サービスは github-pages で十分だと思っている。

ドキュメントサイトを作るのに便利なフレームワークがあるのでちょっと調べてみました。

自分のライブラリのサイトに必要な要素は

  • 概要が伝わるランディングページ
  • getting started
  • ドキュメント
  • example

となっております。 ドキュメントに関しては更新が遅れると使いにくいドキュメントになるのでインターフェースから自動生成して欲しい。 下記の候補が上がった


docusaurus

docusaurus を使えば下記のようなサイトが作成可能です。ドキュメントとソースが紐づいているのがいいと思っている サイト: https://pdf-lib.js.org/docs/api/ ドキュメントソース: https://github.com/Hopding/pdf-lib-docs

MDX で書くことができるのでやろうと思えば割と作り込んだサイトも作成可能


storybook

storybook を使えば簡単にインタラクティブなサンプルを作成できるし、インターフェースの型からドキュメントも作成できる。 ただ、サイドバーがあって~みたいな下記のレイアウトで固定なのか、カスタマイズできる領域が少なくて世界観が作りにくいのかなと思う

storybook-custom-theme

下記のサイトは storybook をつかってサイトを構築しているがシンプルでいいなーと思う反面、世界観があまり作れていないのかなーと思う https://www.mdx-embed.com/

なお、docusaurus と同じように MDX で記述できる。


いいライブラリのサイトってなんだろうともう一度考える

  • コンセプトをしっかり伝えつつ、シンプルで理解しやすい。
  • おお!すごいと思える、実際に触れるものがあること。
  • スタイリッシュでかっこいい。信頼性がある。権威性がある。
  • 豊富なサンプルや汎用性の高さをアピールできること。
  • もしも困った時には解決できるしっかりしたドキュメントがあること。

という感じだろう

うーん。あまり storybook とか docsurus にこだわらずトップページくらいは作りたい なんなら API ドキュメントが貧弱な部分以外は下記の今のサイトが悪いとは思わないかも https://labelmake.jp/javascript-pdf-generator-library/