ドキュメントのトピックタイプ(CTRT)

ページの各トピックは、以下のトピックタイプのいずれかにする必要があります:

ページが短くても、通常コンセプトから始まり、タスクや参考トピックが含まれます。

テクニカルライティングチームは、トピックの種類を示すために頭字語CTRT を使用することがあります。この頭字語は、各トピックタイプの最初の文字を指します。

その他のページとトピックの種類

4 つの主要なトピック タイプのほかに、以下を使用できます:

避けるべきページとトピック

避けるべき

  • 他のページへのリンクだけのページ。ただし、ナビゲーションを助けるトップレベルのページだけは例外です。
  • 1つか2つの文章しかないトピック。このような場合
    • 別のトピックに情報を組み込みます。
    • 文章が別のページにリンクしている場合は、代わりに関連トピックのリンクを使用します。
  • 開始トピック単一の機能の手順を文書化するには、タスクを使用します。一連の手順については、チュートリアルを使用してください。

トピックタイトルのガイドライン

一般的に、トピックのタイトルは

  • 明確かつ直接的であること。一語一語を大切に。
  • 冠詞と前置詞を使いましょう。
  • 大文字と小文字の使い分け
  • 以前のトピックタイトルのテキストを繰り返さないでください。たとえば、マージリクエストに関するページの場合、Troubleshooting merge requests の代わりに、Troubleshooting だけを使用します。
  • 情報の区切りにハイフンを使用しないでください。たとえば、Internal analytics - Architecture の代わりに、Internal analytics architecture またはArchitecture of internal analyticsを使用します。

Markdownにおける見出しレベルのガイドラインも参照してください。

インラインリンクでは不十分な場合は、[関連トピック] というトピックを作成し、関連トピックの順序なしリストを含めることができます。このトピックは、「トラブルシューティング」セクションの上に配置します。

このセクションのリンクは、簡潔で読みやすいものでなければなりません。通常は完全な文章ではないので、ピリオドで終わるべきではありません。

## Related topics

- [CI/CD variables](link-to-topic)
- [Environment variables](link-to-topic)