# General Translation Blog: 人間のためのドキュメント設計
URL: https://generaltranslation.com/ja/blog/designing-docs-for-humans.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: AIの時代にもデザインが重要であり続ける理由と、頭の中の混乱を整理するために私たちが掲げるドキュメント設計の原則。
Authors: Kevin Liu, Taylor Fang
Published: 2026-09-17
## なぜドキュメントをデザインするのか？
ドキュメントは、Webデザインにおける未解決の課題です。パターンとアンチパターンがいたるところに存在し、既成のテンプレートを通じて無限に複製されています。テンプレートは手早く簡単ですが、ドキュメントを、特定のユーザーに向けてデザインすべき製品体験の中核ではなく、後付けのものとして扱ってしまう危険があります。また、定番とされる選択肢は、視覚効果によって過剰にデザインされていることもよくあります。ドキュメントサイトに必要なのは**コンテンツに集中できる、よりシンプルな読む体験**であり、凝ったデザインはマーケティングサイトに任せるべきだと私たちは考えています ([Fumadocsの作者](https://generaltranslation.com/blog/fuma-nama)の哲学に倣っています) 。
しかし、エージェントがドキュメントの読み手、そして書き手の大半を占める世界において、**それでもドキュメントサイトをデザインすべきなのでしょうか？** そもそもなぜ、人間にとっての読みやすさや視覚的なデザインに労力を割く必要があるのでしょうか？
AIによる粗製乱造コンテンツがあふれる世界だからこそ、直感的で意図の込められたドキュメントのインターフェースはいっそう重要になる、と私たちは考えています。この考えは、デザインという営みへの愛着と、自分たちの製品体験へのこだわりから来ています。しかしそれだけでなく、**人間は今なおドキュメントを見て読んでいる**という観察にも基づいています。確かにエージェントはコードを大量に実行しますが、単純な量の統計がすべてを物語るわけではありません。人間は今も、製品を理解し評価するためにドキュメントサイトを訪れます。そして人間はますます、頭の中の混乱を整理し、重要なことへ注意を向けさせてくれるインターフェースを必要としています。
私たちはドキュメントの再デザインをゼロから進め、[コンテンツの書き換え](https://generaltranslation.com/blog/rewriting-our-docs)で探求した並行するユーザージャーニーを出発点としました。ドキュメントのプリミティブはごくわずかです。ナビゲーション、検索、コントロール、リンク、そしてコンテンツ。これらを、線を減らし余白を広く取って配置することで、すっきりとした視覚体験を実現し、最大限のコンポーザビリティを得るためにオープンソースのドキュメントフレームワーク[Fumadocs](https://generaltranslation.com/blog/fuma-nama)を土台としました。
私たちは文章に多大な労力を注いでおり、それを読んでもらいたいと考えています。読む体験を滑らかに、さらには心地よいものにするドキュメントサイトをデザインし、維持し続けることが私たちの変わらぬ目標です。その過程で、いくつかの中核的なデザイン原則が生まれました。その第一は、親しみやすく理解しやすいインターフェースを採用することです。
## 直感的な流れと方向性
ドキュメントは、ユーザーが製品とその仕組みについてのメンタルモデルを構築する手助けとなります。これはドキュメントコンテンツの再構成についてのブログ記事で[以前述べた](https://generaltranslation.com/en-US/blog/rewriting-our-docs)とおりです。今回のデザインも、同じ中核的な思考原則から生まれています。すなわち、意図的で意味のある構成、段階的に明かされる複雑さとカスタマイズ性、そして邪魔にならず、いっそ見えないとさえ感じられるディテールです。
画面の各領域は**ひとまとまりのアクションや出力に対応しており**、ユーザーが「ここにあるはず」と思う場所に機能が現れます。 (一部のユーザーは視覚テーマに強いこだわりがあると分かったため、モード切り替えは2か所に配置しています。)
さらにページ全体が直感的な流れをつくり、**ユーザーを目的の達成へと導きます**。
ドキュメントでは、更新情報を確認するためのChangelog、サポートへの質問、製品デモの申し込みなど、ユーザーが取りたくなるアクションへのリンクを目立たせています。
## 思考の雑然さを取り除く
インターフェースはますます雑然としてきています。「アイブロウテキスト」のような要素、複数の方向に動く脈絡のないアニメーション、 (角が丸い) 余計なボックス——こうしたものはAIによるデザインの典型的な兆候です。**この視覚的な雑然さは、そのまま思考の雑然さにつながります。** 各コンポーネントが、配置や他のコンポーネントとの関係を考慮されないまま、ただ存在するためだけに置かれているとき、意味は失われます。
そこで私たちの最初の仕事は、**思考の雑然さを削ぎ落とす**ことです。つまり、余計な要素を削除すること。今回の場合は、多くの余分な線、リンク、ボタンを削ることでした。
しかしそれは同時に、構造化し、再編成し、徹底的に簡素化することでもあります。とりわけ私たちは、**サイトを構成する概念を整理し、その所在を示す**地図として、ナビゲーションのサーフェスを統合しました。
私たちのサイドバーは、いまや単一のアコーディオンです。革命的には聞こえないかもしれませんが、これはドキュメントサイトでは希少な存在になっています。多くのサイトは、縦にも横にも、複数の場所に複数のセクションナビゲーションバーを表示しているからです。
CIはサイドバーの明確な階層を強制し、すべてが同じ階層に並ぶ気の遠くなるようなリンクとオプションの羅列になることを防ぎます。しかも、その状態は保たれます。リンクをクリックしてもサイドバーのオプションが丸ごと入れ替わったり、戻ろうとしたときに自分の居場所を見失ったりすることはありません。
## 視線を導く
直感的な導線は、インターフェースの中をどう進めばよいかをユーザーに教えてくれるものでもあります。ナビゲーション、コントロール、コンテンツ、アクションのそれぞれで**視覚的な階層をより明確に打ち出すこと**により、重要な箇所へ自然に視線が向かうようにしたいと考えました。
a) 重要な箇所にアイコンを使い、文字びっしりの画面に切れ目をつくる。
b) テキストのセクション間に区切りを増やし、コンテンツをまとめてセクションの切れ目をはっきりさせる。
c) テキストのスタイルに強弱をつける。ドキュメントでは敬遠されがちなイタリック体を使ったり、本文のウェイトを400に下げたりする。
とりわけ、[Linearのドキュメント](https://linear.app/docs)に着想を得て、コンテンツにゆとりを持たせる余白をたっぷり取りたいと考えました。Quickstartsページのリニューアルは、これらの原則を組み合わせた好例と言えるでしょう。
## GT ならではの遊び心
ドキュメントサイトもウェブページである以上、無機質であってはなりません。過剰なデザインでコンテンツへの集中を妨げないよう注意しつつ、GT のブランドの美意識と世界観にドキュメントを馴染ませるため、「マイクロ UI」的なディテールも加えました。
[Fumadocs の象徴的な目次コンポーネント](https://generaltranslation.com/en-US/blog/fuma-nama/#the-fumadocs-design-credo)には、さりげないインタラクションを作り込みました。SVG マスクとしてサーバーサイドレンダリングでも動作し、12px のネストレベルと、ポインターを追う淡いブルーのつまみを備えています。モバイルのドロワーでは同じ形状を静的に描画します。タッチにはホバーがないためです。
同じマスクをサイドバーにも適用しました。あるセクションを上から下までクリックしていくと、ブルーのつまみがレールに沿って滑り、ツリーがネストする箇所では内側へ曲がりながら、行ごとにポインターを追いかけます。
AI っぽいデザインの兆候を打ち消すため、その他の UI プリミティブも吟味しました。アイコンが意味を担う箇所ではソリッドのアイコンを使い、検索やコピーといったコントロールには細いアウトラインの字形を残しています。ボックスの角丸も控えめにしました。スクロールバーは、ネイティブとオーバーレイが混在するデフォルトの状態をやめ、サイドバー・コードブロック・メニューで統一しました。また、言語切り替え機能には旗の絵文字ではなくカスタムの旗の SVG を使い、マットなビジュアルアイコノグラフィーを保ちつつランディングページと揃えています。
そしてもちろん、私たちのドキュメントのローカライゼーション体験は最高水準でなければなりません。余白も揃えも順序も、そのまま保ちます。
## やってはいけないことリスト
この取り組みを進める中で、気づいたアンチパターンをまとめた「やってはいけないことリスト」ができあがりました。
* アイブロウテキスト
* 脈絡のない余計な説明文
* 角を丸めすぎたボックス
* 塗りつぶしになっていないアイコン
* コンテンツの重要度と対応していない不揃いな余白
* ローカライズされていないドキュメント (！)
* ページ内に散在する複数のナビゲーション要素
* 無限に広がっていくように見えるサイドバー
* 何かをクリックするたびに中身が変わるサイドバー
* 今どこにいるのか分からなくなるサイドバー
もちろん、私たちはドキュメントのデザインを継続的に改善し続けています。ご意見・ご感想はいつでも歓迎です。よいドキュメントデザインを！
## Sitemap
See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.