Document that TechnologyRoot is optional (#852)

rdar://124270255

Author: d-ronnqvist

Sources/SwiftDocC/Semantics/Metadata/TechnologyRoot.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021-2023 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2024 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -11,14 +11,33 @@
 import Foundation
 import Markdown
 
-/// A directive to set this page as a documentation root-level node.
+/// Configures an article to become a top-level page.
+///
+/// If your documentation only consists of articles, without any framework documentation or other top-level pages, DocC will use the only article or the article with the same base name as the documentation catalog ('.docc' directory) as the top-level page.
+/// If the documentation doesn't contain an article with the same base name as the documentation catalog, DocC will synthesize a minimal top-level page.
+///
+/// To customize which article is the top-level page of your documentation, add a `TechnologyRoot` directive within a `Metadata` directive in that article:
+///
+/// ```md
+/// # Page Title
 ///
-/// This directive is only valid within a top-level ``Metadata`` directive:
-/// ```
 /// @Metadata {
 ///    @TechnologyRoot
 /// }
 /// ```
+///
+/// > Earlier Versions:
+/// > Before Swift-DocC 6.0, article-only documentation catalogs require one of the articles to be marked as a `TechnologyRoot`.
+///
+/// ### Containing Elements
+///
+/// The following items can include a technology root element:
+///
+/// - ``Metadata``
+///
+/// ## See Also
+///
+/// - <doc:formatting-your-documentation-content>
 public final class TechnologyRoot: Semantic, AutomaticDirectiveConvertible {
     public static let introducedVersion = "5.5"
     public let originalMarkup: BlockDirective

Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/Metadata.md

@@ -20,7 +20,7 @@ Use it with the ``DocumentationExtension`` directive to replace in-source docume
 }
 ```
 
-Use the `Metadata` directive with the ``TechnologyRoot`` directive to configure a documentation page that's not associated with a particular framework, so that page appears as a top-level page.
+Use the `Metadata` directive with the ``TechnologyRoot`` directive to customize which article is the top-level page for a documentation catalog ('.docc' directory) without any framework documentation or other top-level pages.
 
 Use the `Metadata` directive with the ``DisplayName`` directive to configure a symbol's documentation page to use a custom display name.