Structural changes to the DocCDocumentation Catalog #742

sofiaromorales · 2023-10-18T15:03:55Z

Bug/issue #, if applicable: rdar://109449796

Summary

This PR introduces a series of changes to the DocC documentation catalog that aim to bring about a better and easier-to-read structure.

Some of these changes include:

Added a new section Documentation Content.
Arranged content from Formatting Your Documentation Content into Formatting Your Documentation Content Other Formatting Options Adding Images to Your Content and Link to Symbols and Other Content.
Added minor comments about conceptual documentation.
Capitalized third-level titles.
Minor changes to titles and summaries around the catalog content.
Updated the year in the files footers.

Dependencies

N/A

Testing

Steps:

Run docc preview DocCDocumentation.docc
Compare the preview with the content available at https://www.swift.org/documentation/docc.

Related file:
DocCDocumentation.doccarchive.zip

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

Added tests (N/A)
Ran the ./bin/test script and it succeeded
Updated documentation if necessary (N/A)

- Added a new section `Documentation Content`. - Arranged content from `Formatting Your Documentation Content`into `Formatting Your Documentation Content``Other Formatting Options` `Adding Images to Your Content` and `Link to Symbols and Other Content`. - Added minor comments about conceptual documentation. - Capitalized third-level titles. - Minor changes to titles and summaries around the catalog content. - Updated the year in the files footers.

Sources/docc/DocCDocumentation.docc/other-formatting-options.md

- Implemented a fix to assign the correct role for Technology Root articles that are part of single-article-only catalogs or article-only catalogs without any manual curation at the top-level article. - Implemented unit tests to validate the correct assignment of roles for this type of case. - Resolved rdar://117019142 rdar://116419389

- Added `Conceptual Documentation` to the documentation types section.

…tion Content`section

patshaughnessy

Looks good Sofia - thanks for reorganizing and updating these pages. I have a couple thoughts and suggestions.

patshaughnessy · 2023-10-21T00:02:57Z

...es/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/api-reference-syntax.md

@@ -1,10 +1,10 @@
-# API Documentation
+# API and Conceptual Documentation


Reading this edit, I wonder if we should have two separate pages, one for API Documentation and one for Conceptual Documentation? Certainly we want to explain and encourage developers to write articles and add them to their API Documentation. So your edits here look good.

What I mean is maybe we need a new page pointing out that developers can write a series of articles which are neither API Documentation nor a tutorial. A series of standalone markdown articles. In this case if you add a new page for that, then you could just keep the original API Documentation title here and avoid the longer title.

That was my original idea, but the content would be pretty much the same since the directives that apply to 'API Documentation' are the same as those that can be used for 'Conceptual Documentation,' so it would be like repeating the same curation for both pages.

I agree with @patshaughnessy. Primarily, Swift-DocC provides a means for people to create API reference documentation from in-source comments. As an added feature, Swift-DocC provides a means for you to author additional, supporting content, such as articles, tutorials, etc. Not all of the supporting content is "conceptual," so I feel like that's a bit of a misnomer. When I think of "conceptual" content, I think of theory and background information, and the documentation you can produce with Swift-DocC can be much more than theory.

Recommend retitling this page.

@chuckdude What do you think about 'API and Custom Documentation`? any other title suggestion?

The idea here is to highlight that DocC can be used not only for API reference but also as a standalone tool for authoring and creating content, similar to TSPL, for example.

What I mean is maybe we need a new page pointing out that developers can write a series of articles which are neither API Documentation nor a tutorial.

I'm concerned that adding 'Conceptual Documentation' as a new documentation type may be too much of a change. Any thoughts, @patshaughnessy @krilnon @chuckdude?

I still concur with @patshaughnessy's original comment that there should be two separate pages or articles to address content. On one hand, you have API reference material that's a doctype of its own. Next, you have the ability to write articles or tutorials. When it comes to articles, those can be task-based, conceptual, or a combination of both, depending on what you need to support people who will use your framework.

So, the three document types are:

API reference

Articles

Tutorials

The page on Articles should address that they can be purely conceptual, strictly task-based, or a combination of the two. The purpose of an article is to teach developers how to use the API, or to show how to do something (task-based) in a practical sense.

I don't think we should try to wedge API reference and Articles (or Tutorials) into the same article.

...es/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/api-reference-syntax.md

Sources/docc/DocCDocumentation.docc/formatting-your-documentation-content.md

krilnon · 2023-10-23T15:51:49Z

Mirroring my comments from the docs workgroup meeting:

I think our current guidance is to use sentence case for article titles and headings. A fair amount of the DocC docs predate that guidance, though, so I can see how you're going for consistency first.
Most articles should start with gerunds, so the 'Link to symbols' title should be 'Linking to symbols', etc.

- Changed 'Link' to 'Linking' to use preferred gerund form

chuckdude

Provided edits and comments throughout. Please let me know if you have any questions, or would like to discuss the edits and suggestions.

Sources/docc/DocCDocumentation.docc/DocC Documentation.md

...es/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/api-reference-syntax.md

chuckdude · 2023-10-26T21:33:58Z

...es/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/api-reference-syntax.md

@@ -1,10 +1,10 @@
-# API Documentation
+# API and Conceptual Documentation


I agree with @patshaughnessy. Primarily, Swift-DocC provides a means for people to create API reference documentation from in-source comments. As an added feature, Swift-DocC provides a means for you to author additional, supporting content, such as articles, tutorials, etc. Not all of the supporting content is "conceptual," so I feel like that's a bit of a misnomer. When I think of "conceptual" content, I think of theory and background information, and the documentation you can produce with Swift-DocC can be much more than theory.

Recommend retitling this page.

chuckdude · 2023-10-26T21:36:28Z

...es/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/api-reference-syntax.md


 ## Overview

-Use documentation markup, a custom variant of Markdown, to add in-source documentation to your APIs. Then, use DocC to build your documentation and share it with developers.
+Use documentation markup, a custom variant of Markdown, to add in-source documentation to your APIs and author conceptual documentation articles. Then, use DocC to build your documentation and share it with developers.


Again, this isn't just about authoring conceptual articles. Recommend going with something like:

...to add in-source documentation for your API, and provide supporting learning materials — such as articles and tutorials — to help people learn more about your API.

...es/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/api-reference-syntax.md

Sources/docc/DocCDocumentation.docc/other-formatting-options.md

Co-authored-by: Chuck Toporek <76215+chuckdude@users.noreply.github.com>

sofiaromorales · 2023-10-27T15:34:00Z

Thanks for the review, @chuckdude! I've addressed most of the comments. Do you think the requested Copyright change is a blocker for this PR?

chuckdude

Please see my notes, throughout, including:

"All rights reserved." capitalization in the page footers
Comment on the title and content for the article, "API and Conceptual Documentation"

chuckdude · 2023-11-06T19:19:18Z

...es/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/api-reference-syntax.md

@@ -1,10 +1,10 @@
-# API Documentation
+# API and Conceptual Documentation


I still concur with @patshaughnessy's original comment that there should be two separate pages or articles to address content. On one hand, you have API reference material that's a doctype of its own. Next, you have the ability to write articles or tutorials. When it comes to articles, those can be task-based, conceptual, or a combination of both, depending on what you need to support people who will use your framework.

So, the three document types are:

API reference

Articles

Tutorials

The page on Articles should address that they can be purely conceptual, strictly task-based, or a combination of the two. The purpose of an article is to teach developers how to use the API, or to show how to do something (task-based) in a practical sense.

I don't think we should try to wedge API reference and Articles (or Tutorials) into the same article.

Sources/docc/DocCDocumentation.docc/DocC Documentation.md

Sources/docc/DocCDocumentation.docc/adding-images.md

franklinsch · 2023-11-07T14:51:22Z

@chuckdude Thanks for your review! Regarding the "All rights reserved" capitalization—I just wanted to chime in to clarify that the copyright footer in which it appears doesn't appear in the produced documentation, it's only used for copyright purposes in the original Markdown source. It follows the template used across open-source Swift repositories in the Swift organization (e.g., https://github.com/apple/swift/blob/main/CODE_OF_CONDUCT.md?plain=1#L5). Changing that template would be a broader discussion.

- Minor fixes.

chuckdude

Approved. Thank you for making these changes, Sofia. :)

sofiaromorales · 2023-11-28T11:06:03Z

@swift-ci please test

sofiaromorales · 2023-11-28T13:44:08Z

@swift-ci please test

Made content changes to the DocCDocumentation Catalog. - Added a new section `Documentation Content`. - Arranged content from `Formatting Your Documentation Content`into `Formatting Your Documentation Content``Other Formatting Options` `Adding Images to Your Content` and `Link to Symbols and Other Content`. - Added minor comments about conceptual documentation. - Capitalized third-level titles. - Minor changes to titles and summaries around the catalog content. - Updated the year in the files footers. - Changed 'Link' to 'Linking' to use preferred gerund form - Supported image extensions added. - Added documentation about support of hex and html codes. --------- Co-authored-by: Chuck Toporek <76215+chuckdude@users.noreply.github.com>

Made content changes to the DocCDocumentation Catalog. rdar://117262993 - Added a new section `Documentation Content`. - Arranged content from `Formatting Your Documentation Content`into `Formatting Your Documentation Content``Other Formatting Options` `Adding Images to Your Content` and `Link to Symbols and Other Content`. - Added minor comments about conceptual documentation. - Capitalized third-level titles. - Minor changes to titles and summaries around the catalog content. - Updated the year in the files footers. - Changed 'Link' to 'Linking' to use preferred gerund form - Supported image extensions added. - Added documentation about support of hex and html codes. --------- Co-authored-by: Chuck Toporek <76215+chuckdude@users.noreply.github.com>

sofiaromorales requested review from franklinsch, d-ronnqvist, patshaughnessy, ethan-kusters, daniel-grumberg, raul-ramirezl and iamleeg October 18, 2023 15:04

Kyle-Ye reviewed Oct 19, 2023

View reviewed changes

Sources/docc/DocCDocumentation.docc/other-formatting-options.md Outdated Show resolved Hide resolved

- Removed extra blank lines at the bottom of the file.

f8036c9

- Added `Conceptual Documentation` to the documentation types section.

sofiaromorales requested a review from Kyle-Ye October 19, 2023 14:44

- Curated Link to Symbols and Other Contentarticle under `Documenta…

a93a981

…tion Content`section

patshaughnessy approved these changes Oct 21, 2023

View reviewed changes

- Minor content changes

1d13acc

- Changed 'Link' to 'Linking' to use preferred gerund form

chuckdude requested changes Oct 26, 2023

View reviewed changes

sofiaromorales and others added 3 commits October 27, 2023 15:10

Update Sources/docc/DocCDocumentation.docc/DocC Documentation.md

2e64258

Co-authored-by: Chuck Toporek <76215+chuckdude@users.noreply.github.com>

Small content fixes propsed by https://github.com/chuckdude

d6d64c3

Content additions propsed by https://github.com/chuckdude

0d0651d

chuckdude requested changes Nov 6, 2023

View reviewed changes

sofiaromorales and others added 3 commits November 21, 2023 17:22

- Supported image extensions added.

ec67b2c

- Minor fixes.

- Added support of hex and html codes.

cc113da

Merge branch 'main' into 109449796-docc-docs-rearrangement

4dd9bfc

sofiaromorales changed the title ~~Content changes to the DocCDocumentation Catalog~~ Structural changes to the DocCDocumentation Catalog Nov 27, 2023

sofiaromorales requested a review from chuckdude November 27, 2023 19:13

chuckdude approved these changes Nov 27, 2023

View reviewed changes

sofiaromorales merged commit 2084946 into swiftlang:main Nov 28, 2023
2 checks passed

sofiaromorales mentioned this pull request Nov 28, 2023

[5.10] Structural changes to the DocCDocumentation Catalog (#742) #758

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Structural changes to the DocCDocumentation Catalog #742

Structural changes to the DocCDocumentation Catalog #742

sofiaromorales commented Oct 18, 2023 •

edited

Loading

patshaughnessy left a comment

patshaughnessy Oct 21, 2023

sofiaromorales Oct 25, 2023

chuckdude Oct 26, 2023

sofiaromorales Oct 27, 2023 •

edited

Loading

sofiaromorales Oct 30, 2023

chuckdude Nov 6, 2023

krilnon commented Oct 23, 2023

chuckdude left a comment

chuckdude Oct 26, 2023

chuckdude Oct 26, 2023

sofiaromorales commented Oct 27, 2023

chuckdude left a comment

chuckdude Nov 6, 2023

franklinsch commented Nov 7, 2023 •

edited

Loading

chuckdude left a comment

sofiaromorales commented Nov 28, 2023

sofiaromorales commented Nov 28, 2023

		@@ -1,10 +1,10 @@
		# API Documentation
		# API and Conceptual Documentation

Structural changes to the DocCDocumentation Catalog #742

Structural changes to the DocCDocumentation Catalog #742

Conversation

sofiaromorales commented Oct 18, 2023 • edited Loading

Summary

Dependencies

Testing

Checklist

patshaughnessy left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sofiaromorales Oct 27, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

krilnon commented Oct 23, 2023

chuckdude left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sofiaromorales commented Oct 27, 2023

chuckdude left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

franklinsch commented Nov 7, 2023 • edited Loading

chuckdude left a comment

Choose a reason for hiding this comment

sofiaromorales commented Nov 28, 2023

sofiaromorales commented Nov 28, 2023

sofiaromorales commented Oct 18, 2023 •

edited

Loading

sofiaromorales Oct 27, 2023 •

edited

Loading

franklinsch commented Nov 7, 2023 •

edited

Loading