モジュール形式の記述のベスト プラクティス

Draft Space では、コンテンツをトピック内に記述して、再利用できるように最適化します。このモジュール形式で記述するには、従来の記述と比べて習慣を変える必要があります。

モジュール形式の記述に熟達するには、多くの練習が必要です。ただし、小規模な基本ルールに従うことで、制作者に余分な作業を作成することなく、ドキュメントに貢献できます。

モジュール形式の記述の利点

コンテンツを単一目的のトピックに分割することで、再利用や再編成が容易になります。
  • トピックはさまざまなドキュメントに含めることができ、1 つのドキュメントに複製することもできます。
  • トピックの使用場所に関係なく、トピックを 1 回更新します。
  • 多くの制作者や共同作業者は、コンテンツの編成方法を気にすることなく、コンテンツに対して並行して作業を行うことができます。

これらのメリットは、コンテンツが構造や順序の変更から独立した方法で記述されている場合にのみ得られます。

単一目的のトピック

1 つのことについてのみトピックを記述してください。複数のことを説明する必要があると思われる場合は、ためらわずに複数のトピックを作成してください。これらのトピックは、章の冒頭として機能する親トピックの下にリストできます。

適切なタイトルと簡単な説明

読者は最初にタイトルとトピックの先頭のいくつかの単語を見てから、リンクを選択してトピック全体を表示するかどうかを選択します。したがって、その決定にはタイトルと最初の段落が役立ちます。

タイトルは、すべてのトピックをカバーし、トピックのみをカバーする必要があります (単一目的のトピックを作成すると簡単になります)。

簡単な説明 (shortdesc) はトピックの最初の段落となるため、常に作成することを推奨します。読者がタイトルの上にカーソルを置くと、情報チップに簡単な説明が表示されることがよくあります。そのため、そのトピックを読む価値があるかどうかを読者が確認するのに役立ちます。コンテンツを要約するのではなく、コンテンツを紹介します。簡単な説明の長さは、300 文字未満にしておくことをお勧めします。

独立

トピックはドキュメント内で移動できます。一部は追加、一部は削除、一部は並べ替えられる可能性があります。したがって、コンテンツでは、前や後に来る内容を参照しないことが重要です。理想的には、トピックはその周囲に何もないかのように記述する必要があります。実際に、トピックは単独で表示されます。