Slide 1

Slide 1 text

! Navigating DocC Mobiconf | The Internets | October 2021 Ellen Shapiro | @DesignatedNerd | ApolloGraphQL.com @DesignatedNerd

Slide 2

Slide 2 text

No content

Slide 3

Slide 3 text

No content

Slide 4

Slide 4 text

! @DesignatedNerd

Slide 5

Slide 5 text

@DesignatedNerd

Slide 6

Slide 6 text

DocC @DesignatedNerd

Slide 7

Slide 7 text

via instagram.com/sailor.moon.doxie

Slide 8

Slide 8 text

! via instagram.com/sailor.moon.doxie

Slide 9

Slide 9 text

@DesignatedNerd

Slide 10

Slide 10 text

! @DesignatedNerd

Slide 11

Slide 11 text

Doc @DesignatedNerd

Slide 12

Slide 12 text

Doc C @DesignatedNerd

Slide 13

Slide 13 text

!" @DesignatedNerd

Slide 14

Slide 14 text

@DesignatedNerd

Slide 15

Slide 15 text

@DesignatedNerd

Slide 16

Slide 16 text

@DesignatedNerd

Slide 17

Slide 17 text

@DesignatedNerd

Slide 18

Slide 18 text

! @DesignatedNerd

Slide 19

Slide 19 text

@DesignatedNerd

Slide 20

Slide 20 text

Where do I start? @DesignatedNerd

Slide 21

Slide 21 text

You probably already did @DesignatedNerd

Slide 22

Slide 22 text

/// 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

Slide 23

Slide 23 text

/// 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

Slide 24

Slide 24 text

/** 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

Slide 25

Slide 25 text

No content

Slide 26

Slide 26 text

@DesignatedNerd

Slide 27

Slide 27 text

@DesignatedNerd

Slide 28

Slide 28 text

@DesignatedNerd

Slide 29

Slide 29 text

Part 1: Fancifying Swift Documentation @DesignatedNerd

Slide 30

Slide 30 text

Symbol `` Links `` @DesignatedNerd

Slide 31

Slide 31 text

@DesignatedNerd

Slide 32

Slide 32 text

@DesignatedNerd

Slide 33

Slide 33 text

@DesignatedNerd

Slide 34

Slide 34 text

@DesignatedNerd

Slide 35

Slide 35 text

@DesignatedNerd

Slide 36

Slide 36 text

@DesignatedNerd

Slide 37

Slide 37 text

@DesignatedNerd

Slide 38

Slide 38 text

@DesignatedNerd

Slide 39

Slide 39 text

@DesignatedNerd

Slide 40

Slide 40 text

@DesignatedNerd

Slide 41

Slide 41 text

@DesignatedNerd

Slide 42

Slide 42 text

@DesignatedNerd

Slide 43

Slide 43 text

@DesignatedNerd

Slide 44

Slide 44 text

@DesignatedNerd

Slide 45

Slide 45 text

@DesignatedNerd

Slide 46

Slide 46 text

Limitations @DesignatedNerd

Slide 47

Slide 47 text

Limitations (at least for now) @DesignatedNerd

Slide 48

Slide 48 text

Frameworks Packages Applications @DesignatedNerd

Slide 49

Slide 49 text

Frameworks Packages Applications @DesignatedNerd

Slide 50

Slide 50 text

Frameworks Packages Applications @DesignatedNerd

Slide 51

Slide 51 text

Frameworks Packages Applications @DesignatedNerd

Slide 52

Slide 52 text

! Linking to Related Frameworks @DesignatedNerd

Slide 53

Slide 53 text

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

Slide 54

Slide 54 text

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

Slide 55

Slide 55 text

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

Slide 56

Slide 56 text

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

Slide 57

Slide 57 text

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

Slide 58

Slide 58 text

@DesignatedNerd

Slide 59

Slide 59 text

@DesignatedNerd

Slide 60

Slide 60 text

@DesignatedNerd

Slide 61

Slide 61 text

@DesignatedNerd

Slide 62

Slide 62 text

@DesignatedNerd

Slide 63

Slide 63 text

@DesignatedNerd

Slide 64

Slide 64 text

@DesignatedNerd

Slide 65

Slide 65 text

@DesignatedNerd

Slide 66

Slide 66 text

@DesignatedNerd

Slide 67

Slide 67 text

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

Slide 68

Slide 68 text

(Assume this means December 31) @DesignatedNerd

Slide 69

Slide 69 text

@DesignatedNerd

Slide 70

Slide 70 text

@DesignatedNerd

Slide 71

Slide 71 text

DoccZz @DesignatedNerd

Slide 72

Slide 72 text

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

Slide 73

Slide 73 text

@DesignatedNerd

Slide 74

Slide 74 text

@DesignatedNerd

Slide 75

Slide 75 text

@DesignatedNerd

Slide 76

Slide 76 text

@DesignatedNerd

Slide 77

Slide 77 text

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

Slide 78

Slide 78 text

@DesignatedNerd

Slide 79

Slide 79 text

@DesignatedNerd

Slide 80

Slide 80 text

@DesignatedNerd

Slide 81

Slide 81 text

Part 2: Better Information ! Architecture @DesignatedNerd

Slide 82

Slide 82 text

@DesignatedNerd

Slide 83

Slide 83 text

@DesignatedNerd

Slide 84

Slide 84 text

Documentation Catalog @DesignatedNerd

Slide 85

Slide 85 text

@DesignatedNerd

Slide 86

Slide 86 text

@DesignatedNerd

Slide 87

Slide 87 text

@DesignatedNerd

Slide 88

Slide 88 text

@DesignatedNerd

Slide 89

Slide 89 text

@DesignatedNerd

Slide 90

Slide 90 text

@DesignatedNerd

Slide 91

Slide 91 text

@DesignatedNerd

Slide 92

Slide 92 text

ಠ_ಠ @DesignatedNerd

Slide 93

Slide 93 text

@DesignatedNerd

Slide 94

Slide 94 text

@DesignatedNerd

Slide 95

Slide 95 text

@DesignatedNerd

Slide 96

Slide 96 text

@DesignatedNerd

Slide 97

Slide 97 text

@DesignatedNerd

Slide 98

Slide 98 text

@DesignatedNerd

Slide 99

Slide 99 text

@DesignatedNerd

Slide 100

Slide 100 text

@DesignatedNerd

Slide 101

Slide 101 text

@DesignatedNerd

Slide 102

Slide 102 text

@DesignatedNerd

Slide 103

Slide 103 text

@DesignatedNerd

Slide 104

Slide 104 text

@DesignatedNerd

Slide 105

Slide 105 text

@DesignatedNerd

Slide 106

Slide 106 text

@DesignatedNerd

Slide 107

Slide 107 text

@DesignatedNerd

Slide 108

Slide 108 text

@DesignatedNerd

Slide 109

Slide 109 text

Articles @DesignatedNerd

Slide 110

Slide 110 text

@DesignatedNerd

Slide 111

Slide 111 text

@DesignatedNerd

Slide 112

Slide 112 text

@DesignatedNerd

Slide 113

Slide 113 text

Put long doc discussions into dedicated files @DesignatedNerd

Slide 114

Slide 114 text

@DesignatedNerd

Slide 115

Slide 115 text

@DesignatedNerd

Slide 116

Slide 116 text

Part 3: ✨ Shiny Tutorials @DesignatedNerd

Slide 117

Slide 117 text

@DesignatedNerd

Slide 118

Slide 118 text

Markdown Directives @DesignatedNerd

Slide 119

Slide 119 text

@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

Slide 120

Slide 120 text

@DesignatedNerd

Slide 121

Slide 121 text

@DesignatedNerd

Slide 122

Slide 122 text

@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

Slide 123

Slide 123 text

@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

Slide 124

Slide 124 text

@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

Slide 125

Slide 125 text

@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

Slide 126

Slide 126 text

@DesignatedNerd

Slide 127

Slide 127 text

@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

Slide 128

Slide 128 text

@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

Slide 129

Slide 129 text

@DesignatedNerd

Slide 130

Slide 130 text

@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

Slide 131

Slide 131 text

@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

Slide 132

Slide 132 text

@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

Slide 133

Slide 133 text

@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

Slide 134

Slide 134 text

@DesignatedNerd

Slide 135

Slide 135 text

! @DesignatedNerd

Slide 136

Slide 136 text

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

Slide 137

Slide 137 text

Who is Apple building this tool for? @DesignatedNerd

Slide 138

Slide 138 text

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

Slide 139

Slide 139 text

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

Slide 140

Slide 140 text

DocC v1 @DesignatedNerd

Slide 141

Slide 141 text

@DesignatedNerd

Slide 142

Slide 142 text

Obligatory Summary Slide @DesignatedNerd

Slide 143

Slide 143 text

Obligatory Summary Slide → DocC uses Swift Compiler to make your docs shiny @DesignatedNerd

Slide 144

Slide 144 text

Obligatory Summary Slide → DocC uses Swift Compiler to make your docs shiny → Inline documentation is a huge part of the battle @DesignatedNerd

Slide 145

Slide 145 text

Obligatory Summary Slide → DocC uses Swift Compiler to make your docs shiny → Inline documentation is a huge part of the battle → Use a Documentation Catalog to add structure @DesignatedNerd

Slide 146

Slide 146 text

Obligatory Summary Slide → DocC uses Swift Compiler to make your docs shiny → Inline documentation is a huge part of the battle → Use a Documentation Catalog to add structure → Architect your info to be easier to understand @DesignatedNerd

Slide 147

Slide 147 text

Obligatory Summary Slide → DocC uses Swift Compiler to make your docs shiny → Inline documentation is a huge part of the battle → Use a Documentation Catalog to add structure → Architect your info to be easier to understand → Tutorials are shiny but a lot of work @DesignatedNerd

Slide 148

Slide 148 text

Obligatory Summary Slide → DocC uses Swift Compiler to make your docs shiny → Inline documentation is a huge part of the battle → Use a Documentation Catalog to add structure → Architect your info to be easier to understand → Tutorials are shiny but a lot of work → File Radars Feedback! @DesignatedNerd

Slide 149

Slide 149 text

Thank you! @DesignatedNerd

Slide 150

Slide 150 text

Links! → DocC, Archived and Analyzed https:// www.alwaysrightinstitute.com/docz/ → How to Document Your Project With DocC https:// www.hackingwithswift.com/articles/238/how-to- document-your-project-with-docc @DesignatedNerd

Slide 151

Slide 151 text

Links! → Documenting a Swift Framework or Package https://developer.apple.com/documentation/ Xcode/documenting-a-swift-framework-or- package → Formatting Your Documentation Content https:// developer.apple.com/documentation/xcode/ formatting-your-documentation-content @DesignatedNerd