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
  2. /// 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
  3. /// 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
  4. /** 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
  5. → Classes → Structs → Enums → Protocols → Free

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

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

    Functions → Type Aliases → Custom Operators → Extensions of types outside your framework @DesignatedNerd
  8. extension String { /// An extrmely secure cryptographic function ///

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

    /// /// - Returns: The reciever, encrypted. func customEncryption() -> String { return String(self.reversed()) } } @DesignatedNerd
  10. @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
  11. @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
  12. @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
  13. @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
  14. @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
  15. @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
  16. @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
  17. @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
  18. @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
  19. @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
  20. @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
  21. 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
  22. Obligatory Summary Slide → DocC uses Swi Compiler to make

    your docs shiny → Inline documentation is a huge chunk of the battle @DesignatedNerd
  23. 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
  24. 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
  25. 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
  26. 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
  27. 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
  28. 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