ドキュメンテーションの共通ルール

最適なユーザーエクスペリエンスと明確さを提供するために、新しいコンテンツを作成する際には、docs.ton.org をすべてのドキュメントに適用し、一般的かつ重要な要件のリストに留意してください。

プロフェッショナル向けのドキュメント

ドキュメントページは主にドキュメントの目的のために作成されており、チュートリアルとしての使用を意図していないため、テキスト中で個人的な例や比喩の使用を最小限に抑えることが重要です。コンテンツが専門家およびそうでない人の両方に適していることを確保しつつ、有益な情報を提供することが重要です。

一貫したフォーマットを使用する

読者がドキュメントを簡単に追えるようにするためには、ドキュメント全体で一貫したフォーマットを使用することが重要です。見出し、サブ見出し、箇条書き、および番号付きリストを使用して、テキストを区切り、読みやすくしましょう。

特別なセクションで例を挙げる

例を挙げることで、読者はその内容や適用方法をより理解しやすくなります。もしドキュメントページを書いていて、いくつかの例を参照する必要がある場合は、「参考文献」と「また見る」のセクションの前に「例」のセクションを作ってください。ドキュメントページでは、説明と例を混在させないよう気をつけてください。 コード・スニペット、スクリーンショット、図などを使ってポイントを説明し、ドキュメントをより魅力的なものにしてください。

常に最新の状態に

技術文書は、技術の変化やソフトウェアの更新により、すぐに古くなってしまいます。ドキュメンテーションを定期的に見直し、更新することで、正確さとソフトウェアの最新バージョンとの関連性を保つことが重要です。

フィードバックを得る

ドキュメントを公開する前に、他のコントリビューターやユーザーからフィードバックをもらうとよいでしょう。そうすることで、分かりにくかったり、不明瞭だったりする部分を特定し、ドキュメントを公開する前に改善することができます。