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
   

   View Slide

2. Max, via Instagram/Cats_Of_Madison
   

   View Slide

3. Max, via Instagram/Cats_Of_Madison
   

   View Slide

4. !
   @DesignatedNerd
   

   View Slide

5. @DesignatedNerd
   

   View Slide

6. DocC
   @DesignatedNerd
   

   View Slide

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

   View Slide

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

   View Slide

9. @DesignatedNerd
   

   View Slide

10. !
    @DesignatedNerd
    

    View Slide

11. Doc
    @DesignatedNerd
    

    View Slide

12. Doc
    C
    @DesignatedNerd
    

    View Slide

13. !"
    @DesignatedNerd
    

    View Slide

14. C is for Compiler
    @DesignatedNerd
    

    View Slide

15. @DesignatedNerd
    

    View Slide

16. @DesignatedNerd
    

    View Slide

17. !
    @DesignatedNerd
    

    View Slide

18. @DesignatedNerd
    

    View Slide

19. Where do I start?
    @DesignatedNerd
    

    View Slide

20. You probably
    already did
    @DesignatedNerd
    

    View 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 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 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 Slide

24. View Slide

25. @DesignatedNerd
    

    View Slide

26. @DesignatedNerd
    

    View Slide

27. @DesignatedNerd
    

    View Slide

28. Part 1:
    Fancifying Swi
    Documentation
    @DesignatedNerd
    

    View Slide

29. Symbol `` Links ``
    @DesignatedNerd
    

    View Slide

30. @DesignatedNerd
    

    View Slide

31. @DesignatedNerd
    

    View Slide

32. @DesignatedNerd
    

    View Slide

33. @DesignatedNerd
    

    View Slide

34. @DesignatedNerd
    

    View Slide

35. @DesignatedNerd
    

    View Slide

36. @DesignatedNerd
    

    View Slide

37. @DesignatedNerd
    

    View Slide

38. @DesignatedNerd
    

    View Slide

39. @DesignatedNerd
    

    View Slide

40. @DesignatedNerd
    

    View Slide

41. @DesignatedNerd
    

    View Slide

42. @DesignatedNerd
    

    View Slide

43. @DesignatedNerd
    

    View Slide

44. @DesignatedNerd
    

    View Slide

45. Limitations
    @DesignatedNerd
    

    View Slide

46. Limitations
    (at least for now)
    @DesignatedNerd
    

    View Slide

47. Frameworks
    Packages
    Applications
    @DesignatedNerd
    

    View Slide

48. Frameworks
    Packages
    Applications
    @DesignatedNerd
    

    View Slide

49. Frameworks
    Packages
    Applications
    @DesignatedNerd
    

    View Slide

50. Frameworks
    Packages
    Applications
    @DesignatedNerd
    

    View Slide

51. !
    Linking to Related Frameworks
    @DesignatedNerd
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

57. @DesignatedNerd
    

    View Slide

58. @DesignatedNerd
    

    View Slide

59. @DesignatedNerd
    

    View Slide

60. @DesignatedNerd
    

    View Slide

61. @DesignatedNerd
    

    View Slide

62. @DesignatedNerd
    

    View Slide

63. @DesignatedNerd
    

    View Slide

64. @DesignatedNerd
    

    View Slide

65. @DesignatedNerd
    

    View Slide

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

    View Slide

67. (Assume this means December 31)
    @DesignatedNerd
    

    View Slide

68. @DesignatedNerd
    

    View Slide

69. @DesignatedNerd
    

    View Slide

70. DoccZz
    @DesignatedNerd
    

    View Slide

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

    View Slide

72. @DesignatedNerd
    

    View Slide

73. @DesignatedNerd
    

    View Slide

74. @DesignatedNerd
    

    View Slide

75. @DesignatedNerd
    

    View Slide

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

    View Slide

77. @DesignatedNerd
    

    View Slide

78. @DesignatedNerd
    

    View Slide

79. @DesignatedNerd
    

    View Slide

80. Part 2:
    Better Information
    !
    Architecture
    @DesignatedNerd
    

    View Slide

81. @DesignatedNerd
    

    View Slide

82. @DesignatedNerd
    

    View Slide

83. Documentation Catalog
    @DesignatedNerd
    

    View Slide

84. @DesignatedNerd
    

    View Slide

85. @DesignatedNerd
    

    View Slide

86. @DesignatedNerd
    

    View Slide

87. @DesignatedNerd
    

    View Slide

88. @DesignatedNerd
    

    View Slide

89. @DesignatedNerd
    

    View Slide

90. @DesignatedNerd
    

    View Slide

91. ಠ_ಠ
    @DesignatedNerd
    

    View Slide

92. @DesignatedNerd
    

    View Slide

93. @DesignatedNerd
    

    View Slide

94. @DesignatedNerd
    

    View Slide

95. @DesignatedNerd
    

    View Slide

96. @DesignatedNerd
    

    View Slide

97. @DesignatedNerd
    

    View Slide

98. @DesignatedNerd
    

    View Slide

99. @DesignatedNerd
    

    View Slide

100. @DesignatedNerd
     

     View Slide

101. @DesignatedNerd
     

     View Slide

102. @DesignatedNerd
     

     View Slide

103. @DesignatedNerd
     

     View Slide

104. @DesignatedNerd
     

     View Slide

105. @DesignatedNerd
     

     View Slide

106. @DesignatedNerd
     

     View Slide

107. @DesignatedNerd
     

     View Slide

108. Articles
     @DesignatedNerd
     

     View Slide

109. @DesignatedNerd
     

     View Slide

110. @DesignatedNerd
     

     View Slide

111. @DesignatedNerd
     

     View Slide

112. Put long doc discussions into
     dedicated files
     @DesignatedNerd
     

     View Slide

113. @DesignatedNerd
     

     View Slide

114. @DesignatedNerd
     

     View Slide

115. Part 3:
     ✨
     Shiny Tutorials
     @DesignatedNerd
     

     View Slide

116. @DesignatedNerd
     

     View Slide

117. Markdown
     @DesignatedNerd
     

     View Slide

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
     

     View Slide

119. @DesignatedNerd
     

     View Slide

120. @DesignatedNerd
     

     View 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 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 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 Slide

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
     

     View Slide

125. @DesignatedNerd
     

     View 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 Slide

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
     

     View Slide

128. @DesignatedNerd
     

     View 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 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 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 Slide

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
     

     View Slide

133. @DesignatedNerd
     

     View Slide

134. !
     @DesignatedNerd
     

     View Slide

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

     View Slide

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

     View Slide

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

     View Slide

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
     

     View Slide

139. DocC v1
     @DesignatedNerd
     

     View Slide

140. @DesignatedNerd
     

     View Slide

141. Obligatory Summary Slide
     @DesignatedNerd
     

     View Slide

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

     View Slide

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

     View 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
     @DesignatedNerd
     

     View 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
     @DesignatedNerd
     

     View 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
     @DesignatedNerd
     

     View Slide

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
     

     View Slide

148. Thank you!
     @DesignatedNerd
     

     View Slide

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
     

     View Slide

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
     

     View Slide