Various small documentation phrasing updates (#590)

Author: d-ronnqvist

Sources/docc/DocCDocumentation.docc/adding-structure-to-your-documentation-pages.md

@@ -1,6 +1,6 @@
 # Adding Structure to Your Documentation Pages
 
-Arrange symbols into groups and collections that make them easy to find.
+Make symbols easier to find by arranging them into groups and collections.
 
 ## Overview
 
@@ -24,9 +24,10 @@ For more information, see
 ### Customize Your Documentation's Landing Page
 
 A landing page provides an overview of your framework, introduces important 
-terms, and organizes the resources within your documentation catalog to ease 
-the reader's learning path. It's an opportunity for you to discuss key features 
-of your framework and offer motivation for when the reader might want to use 
+terms, and organizes the resources within your documentation catalog — the
+files that enrich your source documentation comments. The landing page is an
+opportunity for you to ease the reader's learning path, discuss key features of
+your technology, and offer motivation for the reader to return to when they need
 it.
 
 For projects that don't include a documentation catalog, DocC generates a 
@@ -40,7 +41,7 @@ of your framework.
 If you need to manually add a landing page to your documentation catalog, use your text editor to create a file to match the name of the framework. For example, for the 
 `SlothCreator` framework, the filename is `SlothCreator.md`.
 
-The first line of content in a landing page is the name of the framework, which 
+The first line of content in a landing page is an H1 heading containing the framework's product module name, which 
 you precede with a single hash (`#`) and encapsulate in a set of double backticks (\`\`).
 
 ```markdown
@@ -61,18 +62,18 @@ Catalog sloths you find in nature and create new adorable virtual sloths.
 
 After the summary, add another blank line and then one or more paragraphs that 
 introduce your framework to form the Overview section of the landing 
-page. Keep the Overview brief — typically less than a screen's worth of 
+page. Try to keep the Overview brief — typically less than a screen's worth of 
 content. Avoid detailing every feature in your framework. Instead, 
 provide content that helps the reader understand what problems the framework 
 solves.
 
-Write your Overview using _documentation markup_; a lightweight markup language 
+Write your Overview using _documentation markup_, a lightweight markup language 
 that allows you to include images, lists, and links to 
 symbols and other content. For more information, see 
 <doc:formatting-your-documentation-content>. 
 
-In addition to presenting rich content, a custom landing page provides organization of the top-level symbols and other content in your 
-documentation hierarchy.
+In addition to presenting rich content, a custom landing page organizes the top-level 
+symbols and other content in your documentation hierarchy.
 
 ### Arrange Top-Level Symbols Using Topic Groups
 
@@ -84,7 +85,7 @@ between those symbols.
 To help readers more easily navigate your framework, arrange symbols into 
 groups with meaningful names. Place important symbols higher on the page, and 
 nest supporting symbols inside other symbols. Use group names that are unique, 
-mutually exclusive, and have clear meaning. Experiment with different 
+mutually exclusive, and clear. Experiment with different 
 arrangements to find what works best for you.
 
 ![A screenshot showing the rendered documentation containing two topic groups: Essentials and Creating Sloths.](4_topics_1)
@@ -125,16 +126,16 @@ symbol's type information and summary. For more information, see
 <doc:formatting-your-documentation-content>.
 
 When you rebuild your documentation, the documentation viewer reflects these 
-organizational changes in the navigation pane and on the framework's 
+organizational changes in the navigation pane and on the 
 landing page, as the image above shows.
 
 ### Arrange Nested Symbols in Extension Files
 
-Not all public symbols appear at the top-level of a framework. For example, 
+Not all symbols appear on the top-level landing page. For example, 
 classes and structures define methods and properties, and in some cases, nested 
 classes or structures introduce additional levels of hierarchy.
 
-As with the framework's landing page, DocC generates default topic groups for 
+As with the top-level landing page, DocC generates default topic groups for 
 nested symbols according to their type. Use extension files to override this 
 default organization and provide a more appropriate structure for your symbols.
 
@@ -143,15 +144,14 @@ default organization and provide a more appropriate structure for your symbols.
 To add an extension file to your documentation catalog for a specific symbol, use a text editor to create a new file named `Extension.md`.
 
 In the `Extension.md` file, replace the `Symbol` placeholder 
-with the name of the symbol you're organizing and rename the file accordingly.
+with the symbol path of the symbol you're organizing and rename the file accordingly.
 
 ```markdown
 # ``SlothCreator/Sloth``
 ```
 
-> Important: You must use the symbol's absolute path for the page title of an 
-extension file and include the name of the framework or package. DocC doesn't 
-support relative symbol paths in this context.
+> Important: The symbol path for the page title of an extension file need to start
+with the name of a top-level symbol or the name of the framework.
 
 The Extension File template includes a `Topics` section with a single named 
 group, ready for you to fill out. Alternatively, if your documentation catalog 
@@ -222,4 +222,4 @@ they can also confuse a reader if you create too many levels of hierarchy.
 Avoid using a collection when a topic group at a higher level can achieve the 
 same result.
 
-<!-- Copyright (c) 2021 Apple Inc and the Swift Project authors. All Rights Reserved. -->
+<!-- Copyright (c) 2021-2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->

Sources/docc/DocCDocumentation.docc/adding-supplemental-content-to-a-documentation-catalog.md

@@ -15,7 +15,7 @@ include this conceptual content. Articles are markup files that contain
 information that doesn't relate to a specific symbol. Use articles to:
 
 * Provide a landing page that includes an overview of your package or framework
-* Craft a learning path for readers to understand how to use your code base, such
+* Craft a learning path for readers to understand how to use your project, such
   as with a getting started guide or a tutorial
 
 Extension files are markup files that complement source documentation
@@ -32,14 +32,14 @@ files, see
 The process of crafting great documentation is an art. Your
 content is unique; you know which elements, beyond source
 documentation comments, provide the most value to your readers. For 
-information about adding documentation to your code base and creating a
+information about adding documentation to your project and creating a
 documentation catalog, see
 <doc:documenting-a-swift-framework-or-package>.
 
 ### Add Articles to Explain Concepts or Describe Tasks
 
 Adding articles to your documentation catalog helps readers understand how
-the types and methods in your code base work as a system. They let you
+the types and methods in your project work as a system. They let you
 explain how to complete a task, or discuss a broader concept that doesn't fit
 into an Overview section for a specific symbol.
 
@@ -48,7 +48,7 @@ into an Overview section for a specific symbol.
 The structure of an article is similar to symbol files or a top-level landing
 page, with the exception that the first level 1 header is regular content instead
 of a symbol reference. For example, the Getting Started with Sloths article
-contains the following title, single-sentence abstract or summary, and overview section:
+contains the following title, single-sentence abstract or summary, and Overview section:
 
 ```markdown
 # Getting Started with Sloths
@@ -64,7 +64,7 @@ habitat.
 
 To add an article to your documentation catalog, use a text editor and create a file with an appropriate title and add a `.md` extension.
 
-After the overview section, additional sections and subsections use a double
+After the Overview section, additional sections and subsections use a double
 hash (##) for a level 2 header, and a triple hash (###) for a level 3 header.
 Follow the hashes with a space, and then the title for that section or
 subsection.
@@ -77,7 +77,7 @@ When you add an article to a documentation catalog, DocC includes a link to it
 on the project's top-level page. To choose a different location for the
 article, add a link to it from a group or collection. When DocC renders a link to
  an article, it uses the article's title for the text of the link. For more information
-about organizing your code base's documentation, see
+about organizing your project's documentation, see
 <doc:adding-structure-to-your-documentation-pages>. 
 
 ### Add Extension Files to Append to or Override Source Documentation Comments
@@ -95,9 +95,8 @@ In cases like these, DocC supports supplementing or completely replacing source
 documentation comments with content in extension files. To add an extension file to your
 documentation catalog, create a file within the documentation catalog, then modify the first line of the file to identify the symbol that the file relates to.
 
-> Important: You must use the symbol's absolute path for the page title of an 
-extension file and include the name of the framework or package. DocC doesn't 
-support relative symbol paths in this context.
+> Important: The symbol path for the page title of an extension file need to start
+with the name of a top-level symbol or the name of the framework.
 
 If the symbol already has source documentation comments, add a
 `DocumentationExtension` directive to specify whether the content of the
@@ -151,7 +150,7 @@ This overrides the in-source summary.
 This content overrides in-source content.
 ````
 
-For additional details about `Metadata` and other directives, see
+For more information on `Metadata` and other directives, see
 <doc:Metadata>.
 
-<!-- Copyright (c) 2021 Apple Inc and the Swift Project authors. All Rights Reserved. -->
+<!-- Copyright (c) 2021-2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->

Sources/docc/DocCDocumentation.docc/documenting-a-swift-framework-or-package.md

@@ -1,69 +1,72 @@
 # Documenting a Swift Framework or Package
 
-Create rich and engaging documentation from your in-source comments, and add a 
-documentation catalog to your code base to provide additional content.
+Create developer documentation from in-source comments, add articles with code snippets, 
+and add tutorials for a guided learning experience.
 
 ## Overview
 
-DocC, or _Documentation Compiler_, makes it easy for you to produce 
-documentation for your Swift frameworks and packages. The compiler builds your 
-documentation by combining comments that you write in-source with extension files, 
+DocC, or _Documentation Compiler_, makes it easy to produce 
+rich and engaging developer documentation for your Swift frameworks and packages. 
+The compiler builds documentation by combining in-source comments with extension files, 
 articles, and other resources, 
 allowing you to create rich and engaging documentation for developers.
 
 With DocC, you provide a combination of reference and conceptual content, and 
 connect it together using powerful organization and linking capabilities. Because you write 
 documentation directly in source, you can use the tools you're already familiar 
-with, such as Git, to track changes you make.
+with, like Git, to track changes.
 
 ### Build Simple Documentation from Your Source Comments
 
 For DocC to compile your documentation, the Swift compiler first builds your Swift framework 
 or package, and stores additional information about its public APIs alongside 
-the compiled artifacts. It then consumes that information and compiles your 
-documentation into a DocC Archive. This process repeats for every Swift 
-framework or package that your target depends on.
+the compiled artifacts. DocC consumes that information and compiles the documentation into a DocC Archive. This process repeats for every Swift framework or package your target depends on.
 
 ![A diagram showing how the Swift compiler turns code into a Swift framework and supplies information about the framework's public APIs to the documentation compiler, which generates a DocC Archive using that information.](docc-compilation-default)
 
 To build documentation for your Swift framework or package, use the DocC command-line interface in preview mode and specify a location. On macOS, DocC monitors the files in the location and recompiles when you make changes. On other platforms, you need to quit and restart DocC to recompile the documentation.
 
 ![A screenshot showing the Sloth structure documentation in its rendered form.](1_sloth)
 
-DocC uses the comments that you write in your source code as the content for the 
+> Tip: You can also use the Swift-DocC Plugin to 
+[build a documentation archive for a Swift package][plugin-docs].
+[plugin-docs]: https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/generating-documentation-for-hosting-online/
+
+DocC uses the comments you write in your source code as the content for the 
 documentation pages it generates. At a minimum, add basic documentation 
 comments to the framework's public symbols so that DocC can use this information as the symbols'
-single-sentence abstracts or summaries. You can also add thorough 
-documentation comments to provide further detail, including information about 
-parameters, return values, and errors. For more information, see 
+single-sentence abstracts or summaries.
+
+Alternatively, add thorough documentation comments to provide further detail, including
+ information about parameters, return values, and errors. For more information, see 
 <doc:writing-symbol-documentation-in-your-source-files>.
 
-### Create Documentation for a Swift Package
+### Configure a Richer Documentation Experience
 
-By default, DocC compiles only your in-source symbol documentation and then 
+By default, DocC compiles only in-source symbol documentation and then 
 groups those symbols together by their kind, such as protocols, classes, 
 enumerations, and so forth. When you want to provide additional content or 
-customize the organization of your framework's symbols, use a documentation 
+customize the organization of symbols, use a documentation 
 catalog.
 
 DocC combines the public API information from the Swift compiler with the 
-contents of the documentation catalog to generate a richer DocC Archive.
+contents of the documentation catalog to generate a much richer DocC Archive.
 
 ![A diagram showing how the Swift compiler turns code into a Swift framework and supplies information about the framework's public APIs to the documentation compiler, which combines that with a documentation catalog to generate a rich DocC Archive.](docc-compilation-catalog)
 
-Use a documentation catalog when you want to include:
+Use a documentation catalog when you want to include any of the following:
 
-* A landing page that introduces your framework and arranges its top-level 
-symbols, as well as extension files that provide custom organization for your 
+* A landing page that introduces a framework and arranges its top-level 
+symbols, as well as extension files that provide custom organization for the 
 symbols' properties and methods. For more information, see 
 <doc:adding-structure-to-your-documentation-pages>.
-* Extension files that supplement your in-source comments, and articles that 
+* Extension files that supplement in-source comments, and articles that 
 provide supporting conceptual content. For more information, see 
 <doc:adding-supplemental-content-to-a-documentation-catalog>.
-* Tutorials that allow you to teach developers your framework's APIs through 
+* Tutorials that teach developers APIs through 
 step-by-step, interactive content. For more information, see 
 <doc:building-an-interactive-tutorial>.
-* Resource files to use in your documentation, such as images and videos.
+* Resource files to use in your documentation, like images and videos.
 
 > Important: To use a documentation catalog in a Swift package, make sure the 
 manifest's Swift tools version is set to `5.5` or later. 
@@ -80,4 +83,4 @@ and publishing your documentation to your [website](https://apple.github.io/swif
 
 - <doc:writing-symbol-documentation-in-your-source-files>
 
-<!-- Copyright (c) 2021 Apple Inc and the Swift Project authors. All Rights Reserved. -->
+<!-- Copyright (c) 2021-2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->

Sources/docc/DocCDocumentation.docc/writing-symbol-documentation-in-your-source-files.md

@@ -23,8 +23,8 @@ mutating public func eat(_ food: Food, quantity: Int) throws -> Int {
 }
 ``` 
 
-To help people who use your API better understand it, follow the steps in the sections below to 
-add documentation comments to the public symbols in your code base. DocC compiles 
+To help the people who use your API have a better understanding of it, follow the steps in the sections below to 
+add documentation comments to the public symbols in your project. DocC compiles 
 those comments and generates formatted documentation that you share with your users. 
 
 ### Add a Basic Description for Each Symbol
@@ -78,6 +78,9 @@ Insert blank lines to break text into separate paragraphs.
 mutating public func eat(_ food: Food, quantity: Int) throws -> Int {
 ``` 
 
+Any paragraphs you add appear below the Discussion header in the symbol 
+reference page that DocC generates. 
+
 When writing content for a Discussion section, use documentation markup. For 
 more information, see <doc:formatting-your-documentation-content>.
 
@@ -88,7 +91,7 @@ summary, or the Discussion section, if you include one. Describe each parameter
 in isolation. Discuss its purpose and, where necessary, the range of acceptable 
 values.
 
-DocC supports two approaches to document the parameters of a 
+DocC supports two approaches for documenting the parameters of a 
 method. You can add a Parameters section, or one or more parameter fields. 
 Both use Markdown's list syntax.
 
@@ -114,7 +117,7 @@ the name of the parameter.
 mutating public func eat(_ food: Food, quantity: Int) throws -> Int {
 ```
 
-After you add documentation for a method’s parameters, preview it in a web browser to see the rendered content.
+After you add documentation for a methods parameters, preview it in a web browser to see the rendered content.
 
 ![A screenshot showing the rendered documentation for the eat(_:quantity:) method.](3_eat)
 
@@ -189,12 +192,12 @@ In addition, DocC includes features that allow you to create even richer
 documentation for your symbols:
 
 * Use symbol links instead of code voice when referring to other symbols in 
-your framework. Symbol links allow you to quickly navigate your framework's 
+your project. Symbol links allow you to quickly navigate your project's 
 documentation when viewing in a browser. For more information, see 
 <doc:formatting-your-documentation-content>.
 * Use extension files to provide additional content for your symbols, such as 
 code examples and images, and to help keep the size of their in-source comments 
 manageable. For more information, see 
 <doc:adding-supplemental-content-to-a-documentation-catalog>.
 
-<!-- Copyright (c) 2021 Apple Inc and the Swift Project authors. All Rights Reserved. -->
+<!-- Copyright (c) 2021-2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->