Navigating DocC - 360iDev, Denver, August 2021

Apple introduced a new documentation framework at WWDC called DocC. Learn more about how it works, how it helps reinforce best practices for inline documentation, and how you can use it to level up both documentation and tutorials for your framework.

Transcript

1. ! Navigating DocC 360iDev | Denver, CO (ZOMG IRL!!) | August 2021 Ellen Shapiro | @DesignatedNerd | ApolloGraphQL.com
2. Max, via Instagram/Cats_Of_Madison
3. Max, via Instagram/Cats_Of_Madison
4. ! @DesignatedNerd
5. @DesignatedNerd
6. DocC @DesignatedNerd
7. via instagram.com/sailor.moon.doxie
8. ! via instagram.com/sailor.moon.doxie
9. @DesignatedNerd
10. ! @DesignatedNerd
11. Doc @DesignatedNerd
12. Doc C @DesignatedNerd
13. !" @DesignatedNerd
14. C is for Compiler @DesignatedNerd
15. @DesignatedNerd
16. @DesignatedNerd
17. ! @DesignatedNerd
18. @DesignatedNerd
19. Where do I start? @DesignatedNerd
20. You probably already did @DesignatedNerd
21. /// Finds the parent folder from a given file path. /// /// - Parameter filePath: The full file path, as a string /// - Returns: The file URL for the parent folder. public static func findParentFolder(from filePath: String) -> URL { let url = URL(fileURLWithPath: filePath) return url.deletingLastPathComponent() } @DesignatedNerd
22. /// Finds the parent folder from a given file path. /// /// - Parameter filePath: The full file path, as a string /// - Returns: The file URL for the parent folder. public static func findParentFolder(from filePath: String) -> URL { let url = URL(fileURLWithPath: filePath) return url.deletingLastPathComponent() } @DesignatedNerd
23. /** Finds the parent folder from a given file path. Parameter filePath: The full file path, as a string Returns: The file URL for the parent folder. */ public static func findParentFolder(from filePath: String) -> URL { let url = URL(fileURLWithPath: filePath) return url.deletingLastPathComponent() } @DesignatedNerd
25. @DesignatedNerd
26. @DesignatedNerd
27. @DesignatedNerd
28. Part 1: Fancifying Swi Documentation @DesignatedNerd
29. Symbol `` Links `` @DesignatedNerd
30. @DesignatedNerd
31. @DesignatedNerd
32. @DesignatedNerd
33. @DesignatedNerd
34. @DesignatedNerd
35. @DesignatedNerd
36. @DesignatedNerd
37. @DesignatedNerd
38. @DesignatedNerd
39. @DesignatedNerd
40. @DesignatedNerd
41. @DesignatedNerd
42. @DesignatedNerd
43. @DesignatedNerd
44. @DesignatedNerd
45. Limitations @DesignatedNerd
46. Limitations (at least for now) @DesignatedNerd
47. Frameworks Packages Applications @DesignatedNerd
48. Frameworks Packages Applications @DesignatedNerd
49. Frameworks Packages Applications @DesignatedNerd
50. Frameworks Packages Applications @DesignatedNerd
51. ! Linking to Related Frameworks @DesignatedNerd
52. → Classes → Structs → Enums → Protocols → Free Functions → Type Aliases → Custom Operators → Extensions of types outside your framework @DesignatedNerd
53. → Classes → Structs → Enums → Protocols → Free Functions → Type Aliases → Custom Operators → Extensions of types outside your framework @DesignatedNerd
54. → Classes → Structs → Enums → Protocols → Free Functions → Type Aliases → Custom Operators → Extensions of types outside your framework @DesignatedNerd
55. extension String { /// An extrmely secure cryptographic function /// /// - Returns: The reciever, encrypted. public func customEncryption() -> String { return String(self.reversed()) } } @DesignatedNerd
56. public extension String { /// An extrmely secure cryptographic function /// /// - Returns: The reciever, encrypted. func customEncryption() -> String { return String(self.reversed()) } } @DesignatedNerd
57. @DesignatedNerd
58. @DesignatedNerd
59. @DesignatedNerd
60. @DesignatedNerd
61. @DesignatedNerd
62. @DesignatedNerd
63. @DesignatedNerd
64. @DesignatedNerd
65. @DesignatedNerd
66. Will be open-sourced "Later this year" @DesignatedNerd
67. (Assume this means December 31) @DesignatedNerd
68. @DesignatedNerd
69. @DesignatedNerd
70. DoccZz @DesignatedNerd
71. https://github.com/DoccZz/servedocc @DesignatedNerd
72. @DesignatedNerd
73. @DesignatedNerd
74. @DesignatedNerd
75. @DesignatedNerd
76. https://github.com/DoccZz/docc2html @DesignatedNerd
77. @DesignatedNerd
78. @DesignatedNerd
79. @DesignatedNerd
80. Part 2: Better Information ! Architecture @DesignatedNerd
81. @DesignatedNerd
82. @DesignatedNerd
83. Documentation Catalog @DesignatedNerd
84. @DesignatedNerd
85. @DesignatedNerd
86. @DesignatedNerd
87. @DesignatedNerd
88. @DesignatedNerd
89. @DesignatedNerd
90. @DesignatedNerd
91. ಠ_ಠ @DesignatedNerd
92. @DesignatedNerd
93. @DesignatedNerd
94. @DesignatedNerd
95. @DesignatedNerd
96. @DesignatedNerd
97. @DesignatedNerd
98. @DesignatedNerd
99. @DesignatedNerd
100. @DesignatedNerd
101. @DesignatedNerd
102. @DesignatedNerd
103. @DesignatedNerd
104. @DesignatedNerd
105. @DesignatedNerd
106. @DesignatedNerd
107. @DesignatedNerd
108. Articles @DesignatedNerd
109. @DesignatedNerd
110. @DesignatedNerd
111. @DesignatedNerd
112. Put long doc discussions into dedicated files @DesignatedNerd
113. @DesignatedNerd
114. @DesignatedNerd
115. Part 3: ✨ Shiny Tutorials @DesignatedNerd
116. @DesignatedNerd
117. Markdown @DesignatedNerd
118. @Tutorials(name: "Working With Apollo iOS") { @Intro(title: "Welcome!") { This tutorial will walk you through using the Apollo iOS SDK to communicate with your GraphQL server. } @Chapter(name: "Setup") { This chapter allows you to pick a tutorial based on which package manager you use. @Image(source: full-logo, alt: "Apollo logo") @TutorialReference(tutorial: "doc:SwiftPMSetup") @TutorialReference(tutorial: "doc:CocoapodsSetup") @TutorialReference(tutorial: "doc:CarthageSetup") } } @DesignatedNerd
119. @DesignatedNerd
120. @DesignatedNerd
121. @Tutorials(name: "Working With Apollo iOS") { @Intro(title: "Welcome!") { This tutorial will walk you through using the Apollo iOS SDK to communicate with your GraphQL server. } @Chapter(name: "Setup") { This chapter allows you to pick a tutorial based on which package manager you use. @Image(source: full-logo, alt: "Apollo logo") @TutorialReference(tutorial: "doc:SwiftPMSetup") @TutorialReference(tutorial: "doc:CocoapodsSetup") @TutorialReference(tutorial: "doc:CarthageSetup") } } @DesignatedNerd
122. @Tutorials(name: "Working With Apollo iOS") { @Intro(title: "Welcome!") { This tutorial will walk you through using the Apollo iOS SDK to communicate with your GraphQL server. } @Chapter(name: "Setup") { This chapter allows you to pick a tutorial based on which package manager you use. @Image(source: full-logo, alt: "Apollo logo") @TutorialReference(tutorial: "doc:SwiftPMSetup") @TutorialReference(tutorial: "doc:CocoapodsSetup") @TutorialReference(tutorial: "doc:CarthageSetup") } } @DesignatedNerd
123. @Tutorials(name: "Working With Apollo iOS") { @Intro(title: "Welcome!") { This tutorial will walk you through using the Apollo iOS SDK to communicate with your GraphQL server. } @Chapter(name: "Setup") { This chapter allows you to pick a tutorial based on which package manager you use. @Image(source: full-logo, alt: "Apollo logo") @TutorialReference(tutorial: "doc:SwiftPMSetup") @TutorialReference(tutorial: "doc:CocoapodsSetup") @TutorialReference(tutorial: "doc:CarthageSetup") } } @DesignatedNerd
124. @Tutorials(name: "Working With Apollo iOS") { @Intro(title: "Welcome!") { This tutorial will walk you through using the Apollo iOS SDK to communicate with your GraphQL server. } @Chapter(name: "Setup") { This chapter allows you to pick a tutorial based on which package manager you use. @Image(source: full-logo, alt: "Apollo logo") @TutorialReference(tutorial: "doc:SwiftPMSetup") @TutorialReference(tutorial: "doc:CocoapodsSetup") @TutorialReference(tutorial: "doc:CarthageSetup") } } @DesignatedNerd
125. @DesignatedNerd
126. @Tutorial(time: 15) { @Intro(title: "Getting Set Up with Swift Package Manager") { This is how you get setup with SPM } @Section(title: "Using Xcode to Add via SwiftPM") { @ContentAndMedia { Xcode has built in support for Swift Package Manager, and you can use it to add Apollo to your project. } @Steps { @Step { Select the `xcodeproj` in your project navigator. @Image(source:select-package-and-project, alt: "The xcodeproj file in the navigator") } @Step { Select the "Package Dependencies" tab. } ... } } } @DesignatedNerd
127. @Tutorial(time: 15) { @Intro(title: "Getting Set Up with Swift Package Manager") { This is how you get setup with SPM } @Section(title: "Using Xcode to Add via SwiftPM") { @ContentAndMedia { Xcode has built in support for Swift Package Manager, and you can use it to add Apollo to your project. } @Steps { @Step { Select the `xcodeproj` in your project navigator. @Image(source:select-package-and-project, alt: "The xcodeproj file in the navigator") } @Step { Select the "Package Dependencies" tab. } ... } } } @DesignatedNerd
128. @DesignatedNerd
129. @Tutorial(time: 15) { @Intro(title: "Getting Set Up with Swift Package Manager") { This is how you get setup with SPM } @Section(title: "Using Xcode to Add via SwiftPM") { @ContentAndMedia { Xcode has built in support for Swift Package Manager, and you can use it to add Apollo to your project. } @Steps { @Step { Select the `xcodeproj` in your project navigator. @Image(source:select-package-and-project, alt: "The xcodeproj file in the navigator") } @Step { Select the "Package Dependencies" tab. } ... } } } @DesignatedNerd
130. @Tutorial(time: 15) { @Intro(title: "Getting Set Up with Swift Package Manager") { This is how you get setup with SPM } @Section(title: "Using Xcode to Add via SwiftPM") { @ContentAndMedia { Xcode has built in support for Swift Package Manager, and you can use it to add Apollo to your project. } @Steps { @Step { Select the `xcodeproj` in your project navigator. @Image(source:select-package-and-project, alt: "The xcodeproj file in the navigator") } @Step { Select the "Package Dependencies" tab. } ... } } } @DesignatedNerd
131. @Tutorial(time: 15) { @Intro(title: "Getting Set Up with Swift Package Manager") { This is how you get setup with SPM } @Section(title: "Using Xcode to Add via SwiftPM") { @ContentAndMedia { Xcode has built in support for Swift Package Manager, and you can use it to add Apollo to your project. } @Steps { @Step { Select the `xcodeproj` in your project navigator. @Image(source:select-package-and-project, alt: "The xcodeproj file in the navigator") } @Step { Select the "Package Dependencies" tab. } ... } } } @DesignatedNerd
132. @Tutorial(time: 15) { @Intro(title: "Getting Set Up with Swift Package Manager") { This is how you get setup with SPM } @Section(title: "Using Xcode to Add via SwiftPM") { @ContentAndMedia { Xcode has built in support for Swift Package Manager, and you can use it to add Apollo to your project. } @Steps { @Step { Select the `xcodeproj` in your project navigator. @Image(source:select-package-and-project, alt: "The xcodeproj file in the navigator") } @Step { Select the "Package Dependencies" tab. } ... } } } @DesignatedNerd
133. @DesignatedNerd
134. ! @DesignatedNerd
135. https://www.jessesquires.com/blog/2021/06/29/apple-docc-great-but-useless-for-oss/
136. Who is Apple building this tool for? @DesignatedNerd
137. Who is Apple building this tool for? → Themselves @DesignatedNerd
138. Who is Apple building this tool for? → Themselves → People who don't have a lot of resources but still want to make good documentation @DesignatedNerd
139. DocC v1 @DesignatedNerd
140. @DesignatedNerd
141. Obligatory Summary Slide @DesignatedNerd
142. Obligatory Summary Slide → DocC uses Swi Compiler to make your docs shiny @DesignatedNerd
143. Obligatory Summary Slide → DocC uses Swi Compiler to make your docs shiny → Inline documentation is a huge chunk of the battle @DesignatedNerd
144. Obligatory Summary Slide → DocC uses Swi Compiler to make your docs shiny → Inline documentation is a huge chunk of the battle → Use a Documentation Catalog to add structure @DesignatedNerd
145. Obligatory Summary Slide → DocC uses Swi Compiler to make your docs shiny → Inline documentation is a huge chunk of the battle → Use a Documentation Catalog to add structure → Architect your information to be easier to understand @DesignatedNerd
146. Obligatory Summary Slide → DocC uses Swi Compiler to make your docs shiny → Inline documentation is a huge chunk of the battle → Use a Documentation Catalog to add structure → Architect your information to be easier to understand → Tutorials are shiny but a lot of work @DesignatedNerd
147. Obligatory Summary Slide → DocC uses Swi Compiler to make your docs shiny → Inline documentation is a huge chunk of the battle → Use a Documentation Catalog to add structure → Architect your information to be easier to understand → Tutorials are shiny but a lot of work → File Radars Feedback! @DesignatedNerd
148. Thank you! @DesignatedNerd
149. Links! → DocC, Archived and Analyzed https:// www.alwaysrightinstitute.com/docz/ → How to Document Your Project With DocC https:// www.hackingwithswi .com/articles/238/how-to- document-your-project-with-docc @DesignatedNerd
150. Links! → Documenting a Swi Framework or Package https://developer.apple.com/documentation/Xcode/ documenting-a-swi -framework-or-package → Formatting Your Documentation Content https:// developer.apple.com/documentation/xcode/ formatting-your-documentation-content → Interactive Tutorials https://developer.apple.com/ documentation/docc/tutorial-syntax @DesignatedNerd