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.

Ellen Shapiro

August 25, 2021
Tweet

More Decks by Ellen Shapiro

Other Decks in Technology

Transcript

  1. !
    Navigating DocC
    360iDev | Denver, CO (ZOMG IRL!!) | August 2021
    Ellen Shapiro | @DesignatedNerd | ApolloGraphQL.com

    View full-size slide

  2. Max, via Instagram/Cats_Of_Madison

    View full-size slide

  3. Max, via Instagram/Cats_Of_Madison

    View full-size slide

  4. !
    @DesignatedNerd

    View full-size slide

  5. @DesignatedNerd

    View full-size slide

  6. DocC
    @DesignatedNerd

    View full-size slide

  7. via instagram.com/sailor.moon.doxie

    View full-size slide

  8. !
    via instagram.com/sailor.moon.doxie

    View full-size slide

  9. @DesignatedNerd

    View full-size slide

  10. !
    @DesignatedNerd

    View full-size slide

  11. Doc
    @DesignatedNerd

    View full-size slide

  12. Doc
    C
    @DesignatedNerd

    View full-size slide

  13. !"
    @DesignatedNerd

    View full-size slide

  14. C is for Compiler
    @DesignatedNerd

    View full-size slide

  15. @DesignatedNerd

    View full-size slide

  16. @DesignatedNerd

    View full-size slide

  17. !
    @DesignatedNerd

    View full-size slide

  18. @DesignatedNerd

    View full-size slide

  19. Where do I start?
    @DesignatedNerd

    View full-size slide

  20. You probably
    already did
    @DesignatedNerd

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  24. @DesignatedNerd

    View full-size slide

  25. @DesignatedNerd

    View full-size slide

  26. @DesignatedNerd

    View full-size slide

  27. Part 1:
    Fancifying Swi
    Documentation
    @DesignatedNerd

    View full-size slide

  28. Symbol `` Links ``
    @DesignatedNerd

    View full-size slide

  29. @DesignatedNerd

    View full-size slide

  30. @DesignatedNerd

    View full-size slide

  31. @DesignatedNerd

    View full-size slide

  32. @DesignatedNerd

    View full-size slide

  33. @DesignatedNerd

    View full-size slide

  34. @DesignatedNerd

    View full-size slide

  35. @DesignatedNerd

    View full-size slide

  36. @DesignatedNerd

    View full-size slide

  37. @DesignatedNerd

    View full-size slide

  38. @DesignatedNerd

    View full-size slide

  39. @DesignatedNerd

    View full-size slide

  40. @DesignatedNerd

    View full-size slide

  41. @DesignatedNerd

    View full-size slide

  42. @DesignatedNerd

    View full-size slide

  43. @DesignatedNerd

    View full-size slide

  44. Limitations
    @DesignatedNerd

    View full-size slide

  45. Limitations
    (at least for now)
    @DesignatedNerd

    View full-size slide

  46. Frameworks
    Packages
    Applications
    @DesignatedNerd

    View full-size slide

  47. Frameworks
    Packages
    Applications
    @DesignatedNerd

    View full-size slide

  48. Frameworks
    Packages
    Applications
    @DesignatedNerd

    View full-size slide

  49. Frameworks
    Packages
    Applications
    @DesignatedNerd

    View full-size slide

  50. !
    Linking to Related Frameworks
    @DesignatedNerd

    View full-size slide

  51. → Classes
    → Structs
    → Enums
    → Protocols
    → Free Functions
    → Type Aliases
    → Custom Operators
    → Extensions of types outside your framework
    @DesignatedNerd

    View full-size slide

  52. → Classes
    → Structs
    → Enums
    → Protocols
    → Free Functions
    → Type Aliases
    → Custom Operators
    → Extensions of types outside your framework
    @DesignatedNerd

    View full-size slide

  53. → Classes
    → Structs
    → Enums
    → Protocols
    → Free Functions
    → Type Aliases
    → Custom Operators
    → Extensions of types outside your framework
    @DesignatedNerd

    View full-size slide

  54. extension String {
    /// An extrmely secure cryptographic function
    ///
    /// - Returns: The reciever, encrypted.
    public func customEncryption() -> String {
    return String(self.reversed())
    }
    }
    @DesignatedNerd

    View full-size slide

  55. public extension String {
    /// An extrmely secure cryptographic function
    ///
    /// - Returns: The reciever, encrypted.
    func customEncryption() -> String {
    return String(self.reversed())
    }
    }
    @DesignatedNerd

    View full-size slide

  56. @DesignatedNerd

    View full-size slide

  57. @DesignatedNerd

    View full-size slide

  58. @DesignatedNerd

    View full-size slide

  59. @DesignatedNerd

    View full-size slide

  60. @DesignatedNerd

    View full-size slide

  61. @DesignatedNerd

    View full-size slide

  62. @DesignatedNerd

    View full-size slide

  63. @DesignatedNerd

    View full-size slide

  64. @DesignatedNerd

    View full-size slide

  65. Will be open-sourced
    "Later this year"
    @DesignatedNerd

    View full-size slide

  66. (Assume this means December 31)
    @DesignatedNerd

    View full-size slide

  67. @DesignatedNerd

    View full-size slide

  68. @DesignatedNerd

    View full-size slide

  69. DoccZz
    @DesignatedNerd

    View full-size slide

  70. https://github.com/DoccZz/servedocc
    @DesignatedNerd

    View full-size slide

  71. @DesignatedNerd

    View full-size slide

  72. @DesignatedNerd

    View full-size slide

  73. @DesignatedNerd

    View full-size slide

  74. @DesignatedNerd

    View full-size slide

  75. https://github.com/DoccZz/docc2html
    @DesignatedNerd

    View full-size slide

  76. @DesignatedNerd

    View full-size slide

  77. @DesignatedNerd

    View full-size slide

  78. @DesignatedNerd

    View full-size slide

  79. Part 2:
    Better Information
    !
    Architecture
    @DesignatedNerd

    View full-size slide

  80. @DesignatedNerd

    View full-size slide

  81. @DesignatedNerd

    View full-size slide

  82. Documentation Catalog
    @DesignatedNerd

    View full-size slide

  83. @DesignatedNerd

    View full-size slide

  84. @DesignatedNerd

    View full-size slide

  85. @DesignatedNerd

    View full-size slide

  86. @DesignatedNerd

    View full-size slide

  87. @DesignatedNerd

    View full-size slide

  88. @DesignatedNerd

    View full-size slide

  89. @DesignatedNerd

    View full-size slide

  90. ಠ_ಠ
    @DesignatedNerd

    View full-size slide

  91. @DesignatedNerd

    View full-size slide

  92. @DesignatedNerd

    View full-size slide

  93. @DesignatedNerd

    View full-size slide

  94. @DesignatedNerd

    View full-size slide

  95. @DesignatedNerd

    View full-size slide

  96. @DesignatedNerd

    View full-size slide

  97. @DesignatedNerd

    View full-size slide

  98. @DesignatedNerd

    View full-size slide

  99. @DesignatedNerd

    View full-size slide

  100. @DesignatedNerd

    View full-size slide

  101. @DesignatedNerd

    View full-size slide

  102. @DesignatedNerd

    View full-size slide

  103. @DesignatedNerd

    View full-size slide

  104. @DesignatedNerd

    View full-size slide

  105. @DesignatedNerd

    View full-size slide

  106. @DesignatedNerd

    View full-size slide

  107. Articles
    @DesignatedNerd

    View full-size slide

  108. @DesignatedNerd

    View full-size slide

  109. @DesignatedNerd

    View full-size slide

  110. @DesignatedNerd

    View full-size slide

  111. Put long doc discussions into
    dedicated files
    @DesignatedNerd

    View full-size slide

  112. @DesignatedNerd

    View full-size slide

  113. @DesignatedNerd

    View full-size slide

  114. Part 3:

    Shiny Tutorials
    @DesignatedNerd

    View full-size slide

  115. @DesignatedNerd

    View full-size slide

  116. Markdown
    @DesignatedNerd

    View full-size slide

  117. @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

    View full-size slide

  118. @DesignatedNerd

    View full-size slide

  119. @DesignatedNerd

    View full-size slide

  120. @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

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  124. @DesignatedNerd

    View full-size slide

  125. @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

    View full-size slide

  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

    View full-size slide

  127. @DesignatedNerd

    View full-size slide

  128. @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

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  132. @DesignatedNerd

    View full-size slide

  133. !
    @DesignatedNerd

    View full-size slide

  134. https://www.jessesquires.com/blog/2021/06/29/apple-docc-great-but-useless-for-oss/

    View full-size slide

  135. Who is Apple building this tool for?
    @DesignatedNerd

    View full-size slide

  136. Who is Apple building this tool for?
    → Themselves
    @DesignatedNerd

    View full-size slide

  137. 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

    View full-size slide

  138. DocC v1
    @DesignatedNerd

    View full-size slide

  139. @DesignatedNerd

    View full-size slide

  140. Obligatory Summary Slide
    @DesignatedNerd

    View full-size slide

  141. Obligatory Summary Slide
    → DocC uses Swi Compiler to make your docs shiny
    @DesignatedNerd

    View full-size slide

  142. Obligatory Summary Slide
    → DocC uses Swi Compiler to make your docs shiny
    → Inline documentation is a huge chunk of the battle
    @DesignatedNerd

    View full-size slide

  143. 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

    View full-size slide

  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
    → Architect your information to be easier to understand
    @DesignatedNerd

    View full-size slide

  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
    → Tutorials are shiny but a lot of work
    @DesignatedNerd

    View full-size slide

  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
    → File Radars Feedback!
    @DesignatedNerd

    View full-size slide

  147. Thank you!
    @DesignatedNerd

    View full-size slide

  148. 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

    View full-size slide

  149. 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

    View full-size slide