[Swift DocC] 문서 만들기 03 - 튜토리얼

Swift DocC

지난 글에서 Swift DocC를 사용해 Article을 만들었습니다. 이번 글에서는 Swift DocC의 마지막 기능인 튜토리얼(Tutorial)을 만들어 보겠습니다.

 

이전 글을 아직 못 보셨다면 보고 오시는 걸 추천드립니다!

 

[Swift DocC] 개념과 기능 (with WWDC)

[Swift DocC] 문서 만들기 01 - Reference 만들기

[Swift DocC] 문서 만들기 02 - Article(설명 글) 만들기

 

 

 

튜토리얼(Tutorial)이란?

 

https://developer.apple.com/tutorials/swiftui

 

앱, 프레임워크, 패키지를 위한 설명서입니다. SwiftUI 튜토리얼을 해보신 분이라면 익숙할 것입니다.

 

https://developer.apple.com/tutorials/swiftui/creating-and-combining-views

 

설명, 코드, 이미지를 활용해 사용자의 이해를 돕고 손쉽게 사용할 수 있도록 해줍니다.

 

DocC를 사용하면 손쉽게 튜토리얼을 만들 수 있습니다!

 

 

 

튜토리얼을 만들 때 중요한 건 기능별로 분류하는 것입니다. 기능별이라고 하면 어떻게 나눠야할지 고민할 수 있는데 간단하게 CRUD를 생각하면 됩니다.

 

내가 만든 프레임워크를 다른 개발자가 사용한다고 하면 특정 기능을 사용하기 위해 객체를 생성하고, 사용하고, 관리하고, 해제하는 과정을 거칠 것입니다. 각각의 과정에 대해서 어떻게 사용하면 될지 설명해주면 됩니다. 

 

 

 

WWDC에 나온 예시를 확인해보겠습니다. WWDC 2021 - Build interactive tutorials using DocC

 

예시에서는 나무늘보를 다루는 앱을 예제로 다룹니다.

 

WWDC 2021 - Build interactive tutorials using DocC

 

기능을 나무늘보를 생성하고, 관리하고, 상호작용하는 것 3가지로 크게 분류했습니다.

 

 

WWDC 2021 - Build interactive tutorials using DocC

 

 

각각의 기능에 대해서 해야할 일을 다룹니다. 생성 과정에서는 View를 만들고, 능력을 주며, 악세사리를 추가하네요.

 

 

WWDC 2021 - Build interactive tutorials using DocC

 

 

 

 

 

튜토리얼 만들기

이전 글에서 사용한 애플 전자기기 - 예제 프로젝트를 통해 튜토리얼을 만들어 보겠습니다.

 

 

우선 Documentation Catalog안에 Tutorial 디렉토리를 생성해서 관리하겠습니다.

 

Documentation Catalog - Tutorials

 

 

가장 먼저 튜토리얼 메인 페이지를 만들기 위해 Tutorail Table of Contetns File을 생성합니다.

 

 

 

메인 튜토리얼 이름은 프로젝트 이름과 동일하게 해주었습니다. (ElectronicsView.tutorial)

 

 

@Intro에는 튜토리얼의 전체적인 설명, @Chatper에는 튜토리얼 목차를 작성하게 됩니다.

 

 

@TutorialReferene에 doc:튜토리얼 파일 이름을 작성해주면 됩니다.

 

 

주의! -> 파일이름에 공백을 넣을 경우 -를 작성해줘야 합니다. 예시의 경우 Creating Electronics View.turoial 라는 파일을 생성했기 때문에 공백자리에 -를 넣어줬습니다.

 

 

 

 

그 다음으로 튜토리얼 파일을 하나 새로 만들어줍니다.

 

Turtorail File 생성

 

 

이름은 Creating Electronics View로 해주었습니다. (띄어쓰기 들어가도 상관없습니다)

 

 

Tutorail File을 생성하면 기본틀이 있습니다. 하나씩 채워주겠습니다.

 

 

 

@Intro에는 튜토리얼에서 설명하고자 하는 대략적인 개요를 적어주면 됩니다.

 

 

 

@Image의 경우 백그라운드 이미지로 들어갑니다.

 

+ 이미지의 경우 문자열로 작성해도 되고, 그냥 작성해도 됩니다. 2개다 된다는 걸 보여주기 위해 코드에서는 섞어 사용했습니다.

 

Intro

 

 

 

@Section의 경우 튜토리얼의 목차에 해당합니다. 예시 프로젝트는 간단한 사용법만 다루기 때문에 하나의 섹션만 사용했습니다.

 

@Section

 

Section

 

 

 

WWDC 예시로 보면 아래와 같이 Section을 나눌 수 있습니다.

 

 

 

 

 

@Step에 각각의 단계에 해당하는 설명, 코드 이미지를 추가해주면 됩니다.

 

 

 

@Image와 @Code를 사용해 설명이 가능합니다. Code에 들어가는 swift 파일의 경우 Documentation Catalog안에 새로 생성해줘야 합니다. 프로젝트 파일에 있는 코드는 인식을 못하네요.

 

 

01-creating-01-01.swift라는 파일을 생성하고 코드를 작성했습니다.

 

파일 이름은 챕터-챕터이름-섹션-파일번호.swift로 작성했습니다. 정해진 건 아니지만 WWDC를 보니 이 컨벤션을 사용하길래 따라 작성했습니다 🤣

 

 

 

@Code에 블럭 { } 을 생성해서 preview를 보여줄 수 있습니다. 꼭 @Image가 아니더라도 @Code도 가능합니다. (저는 귀찮아서 이미지로 ㅎ)

 

 

 

 

 

튜토리얼을 완성했습니다! 문서를 빌드해보면 튜토리얼을 확인할 수 있습니다. (Ctrl + Cmd + Shift + D)

 

 

튜토리얼 확인

 

메인 테이블을 확인할 수 있습니다.

 

메인 Table

 

 

chatper를 클릭해서 들어가서 확인해보면 

 

 

코드랑 같이 확인할 수가 있습니다!

 

 

 

 

정리

DocC의 3가지 기능 중 마지막 기능인 튜토리얼을 만들어보았습니다. 튜토리얼을 만들면서 코드를 자체 리뷰하고 코드 퀄리티가 증가하는 부수적인 효과도 있습니다!

 

 

이미지를 캡처하고 정리하는게 조금 귀찮긴 하지만, 새로운 사용자에게는 이보다 좋은 입문서는 없을 것 같습니다. DocC를 이용해 쉽고 빠르게 튜토리얼을 만들어보세요!

 

 

다음 글에서는 이제까지 만들어온 문서들을 배포해보도록 하겠습니다.

 

[Swift DocC] 문서 만들기 04 - Github 배포

 

 

DocC로 튜토리얼 만들기

 

끝

끗

끝

 

 

 

출처

 

Build interactive tutorials using DocC - WWDC21 - Videos - Apple Developer