Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Navigating DocC - 360iDev, Denver, August 2021

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.

C4861b1dfdf3bbb21faec4a1acdf183d?s=128

Ellen Shapiro
PRO

August 25, 2021
Tweet

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
  24. None
  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