正直なところ、技術文書で一番頭を悩ませるのは、抽象的な概念をいかに理解しやすくするかということだ。先週、私は典型的な状況に遭遇した。新しいインターン生にマイクロサービス・アーキテクチャを説明するために、半日、テキストの説明に頼って話し、彼らの混乱した目を見て、私は突然気づいた。

正しいチャートの種類を選ぶことが重要
ドキュメントの種類によって、必要なビジュアライゼーションは異なる。アーキテクチャー文書にはアーキテクチャー図、プロセス記述にはフローチャート、データ関係にはER図を使う。これは常識のように聞こえるが、多くの人は混乱するだけだ。システム・アーキテクチャを示すためにマインドマップを使っている人を見たことがあるが、明確な階層関係を台無しにしてしまう。例えば、ユーザーログインのプロセスを説明したいのであれば、コンポーネント間の相互作用の順序を明確に示すことができるため、アーキテクチャ図よりもタイミング図の方が適切でしょう。
視覚的な一貫性を保つことが基本
これはとても重要なことだ!私は、さまざまな色、さまざまなフォントサイズ、そして矢印のスタイルさえも統一されていない図表がある技術文書をかなり見てきた。この視覚的混乱は、読書体験に深刻な影響を与える。主な色は何か、どの副次的な色を選ぶか、フォントサイズはどう設定するか、連結線の太さやスタイルはどう統一するかなど、始める前に一連のデザイン仕様を定義しておくことをお勧めします。Smart Excalidrawのように、自動的に視覚的な一貫性を維持することができ、調整の手間を省くことができます。
ヒエラルキーは明確に見えるべきである
技術文書で一番怖いのは、単純な問題を複雑にしてしまうことだ。良い視覚化とは、読者が一目でどこに焦点があり、どのような階層構造になっているかがわかるようにすることである。例えば、アーキテクチャー図では、核となるコンポーネントはより目を引く色や大きなサイズにし、二次的なコンポーネントは適切に弱めることができる。合理的なレイアウトとグループ化によって、情報の階層が自然に示される。以前、システム・アーキテクチャ図を最適化したことがあるが、コンポーネントの位置と大きさを調整しただけで、アーキテクチャ全体の階層関係が2倍以上明確になったことを覚えている。
ノートとタグはちょうどいい
重要なのは、チャートにできるだけ多くの説明を書き込むことではなく、必要な場所に必要な表示をすることである。私はいくつかのチャートを見てきたが、各コンポーネントが指示でいっぱいに書かれており、その結果、人々はむしろフォーカスを見つけることができない。実際には、唯一のキーノードである必要があり、簡潔な説明で十分な場所にあいまいさを生成するのは簡単です。Smart Excalidrawのようなツールは良い、それは混雑していないように見えるうまく配置されたノートを持つ図を生成します。
結局のところ、技術文書の視覚化で最も重要なのは、いかに美しく図を描くかではなく、いかに効率的に情報を伝えるかである。時には、意味を正確に伝えることができる限り、シンプルなスケッチの方が、派手ではあるが図の複雑さに焦点を当てた不明瞭なものよりも価値があることもある。結局のところ、私たちの技術文書の目的は理解されることであり、見せびらかすことではない。
评论列表 (4条):
加载更多评论 読み込み中...