소프트웨어 튜토리얼 작성 규칙
(refactoringenglish.com)- 대부분의 소프트웨어 튜토리얼은 중요한 세부사항을 빠뜨리거나 독자의 기대에 맞지 않는 숨겨진 가정을 포함하여 독자가 과정을 재현할 수 없게 만듦
- 간단한 몇 가지 규칙을 따르면 탁월한 튜토리얼을 작성하는 것이 생각보다 쉬움
규칙
- 초보자를 위한 글쓰기
- 명확한 결과를 약속하는 제목 작성
- 도입부에서 목표 설명
- 최종 결과 미리 보여주기
- 복사/붙여넣기 가능한 코드 스니펫 작성
- 명령어에서 긴 플래그 사용
- 사용자 정의 값과 재사용 가능한 로직 분리
- 독자의 수고 줄이기
- 코드가 항상 작동 상태로 유지되도록 작성
- 하나의 주제만 가르치기
- 꾸미기보다 명확성 우선
- 종속성 최소화
- 파일 이름 명확히 지정
- 일관성 있고 설명적인 제목 사용
- 솔루션이 작동함을 입증
- 완전한 예제 연결
초보자를 위한 글쓰기
- 튜토리얼의 가장 흔한 실수는 초보자 수준의 개념을 전문가 수준의 용어로 설명하는 것. 대부분의 튜토리얼을 찾는 사람들은 초보자임.
- 프로그래밍에 초보자가 아닐 수도 있지만 배우고자 하는 도메인에는 초보자임
- 초보자를 대상으로 작성하며, 전문가 수준의 용어 사용을 지양함
- 어려운 용어를 피하고 독자가 이해할 수 있는 간단한 언어로 작성
- 예를 들어 React 튜토리얼에서는 "JSX transpilation" 대신 "React를 사용한 간단한 웹 페이지 생성"과 같은 설명 제공
명확한 결과를 약속하는 제목 작성
- 제목은 독자가 튜토리얼을 통해 무엇을 배울 수 있는지 구체적으로 전달해야 함
- 불명확하거나 모호한 제목을 피하고, 기대 결과를 명확히 설명
- 예: "Build a Real-Time Twitter Clone in 15 Minutes with Phoenix LiveView"
도입부에서 목표 설명
- 독자가 튜토리얼을 클릭하면, 당신의 말에 관심이 있는 것임. 그러나 계속 읽도록 설득해야 함
- 독자가 궁금한 것은 두가지
- 이 기술에 관심을 가져야 하는가?
- 관심이 있다면, 이 튜토리얼이 나에게 적합한가?
- 도입부에서 기술의 중요성과 튜토리얼의 유용성을 간결하게 설명
- 독자가 관심을 가지도록 유용한 정보를 제공하며, 모호한 서술을 지양함
- 예: Docker 튜토리얼은 Docker가 해결하는 문제와 기대되는 결과를 명확히 설명
최종 결과 미리 보여주기
- 가능한 한 빨리, 독자가 튜토리얼을 통해 만들게 될 작업 데모나 스크린샷을 보여줄 것
- 튜토리얼 초반에 최종 결과를 보여주어 목표를 명확히 함
- 예: 최종 제품의 스크린샷, UI, 동작 예제 등 제공
복사/붙여넣기 가능한 코드 스니펫 작성
- 독자가 코드를 쉽게 복사하여 편집기나 터미널에 붙여넣기하여 실행할 수 있도록 작성
- 터미널 프롬프트 문자
$와 같은 불필요한 요소 제거 - 비대화형 플래그를 사용하여 명령어를 간소화하고, 실패 시 중단되도록
&&를 사용
명령어에서 긴 플래그 사용
- 명령어에서 짧은 플래그 대신 설명이 명확한 긴 플래그를 사용하여 초보자도 쉽게 이해하도록 작성
-
-r보다는--recursive
-
사용자 정의 값과 재사용 가능한 로직 분리
- 코드에서 사용자가 수정해야 할 값과 수정하지 말아야 할 코드를 명확히 분리
- 환경 변수를 사용해 사용자 정의 값을 정의하고 코드의 가독성을 높임
독자의 수고 줄이기
- 독자가 튜토리얼을 좋아할 수 있도록 그들의 시간을 존중하기
- 따분한 작업을 하지 않도록 명령어 스니펫으로 대체
- 예: 수동으로 파일을 수정하는 대신 명령어로 해결
코드가 항상 작동 상태로 유지되도록 작성
- 예제 코드는 항상 실행 가능해야 하며, 중간 단계에서도 작동 상태를 유지하기
- 잘못된 코드나 작동하지 않는 예제는 독자에게 혼란을 초래
하나의 주제만 가르치기
- 튜토리얼은 단일 주제를 중심으로 작성하며, 관련 없는 기술을 혼합하지 않음
- 예를 들어, 검색 기능을 설명하는 튜토리얼에 불필요한 AI 기술을 추가하지 않음
꾸미기보다 명확성 우선
- 독자는 장난감 애플리케이션이 아름답게 보이는지 신경 쓰지 않음
- 불필요한 CSS나 디자인 요소를 최소화하고, 핵심 개념에 집중
- 복잡한 예제 대신 간단한 코드로 개념을 명확히 전달
종속성 최소화
- 독자가 설치해야 하는 종속성을 최소화하여 튜토리얼의 접근성을 높임
- 필수 종속성을 명확히 지정하고, 특정 버전을 명시
파일 이름 명확히 지정
- 독자에게 수정해야 할 파일 경로와 내용을 정확히 안내
- 예를 들어, "config 파일에 설정 추가" 대신 전체 파일 경로와 정확히 어느줄을 편집해야 하는지 구체적인 코드 제공
일관성 있고 설명적인 제목 사용
- 독자가 튜토리얼을 스캔하기 쉽게 구조화된 헤딩 사용
- 제목을 사용하여 튜토리얼을 구조화하고, 논리적인 구조를 반영하도록 제목을 작성하기
- 제목의 형식, 시점, 시제를 일관성 있게 유지
솔루션이 작동함을 입증
- 튜토리얼이 도구 설치나 여러 구성 요소 통합을 가르친다면, 결과를 사용하는 방법을 보여주기
- 설치 및 통합된 도구의 작동 결과를 독자에게 시각적으로 보여줌
- 예를 들어, nginx 성공 페이지를 보여주고 URL을 통해 확인 방법 제공
완전한 예제 연결
- 튜토리얼의 모든 코드를 포함한 레포지토리를 연결하여 전체 흐름을 확인 가능하게 제공
- 각 단계의 코드를 별도의 git 브랜치로 나누어 독자가 각 단계를 따라갈 수 있도록 함
프레임워크의 따분한 기초 사용법을 보여주기 보단,
이 프레임워크가 얼마나 멋진지 보여주고자 하는 튜토리얼 문서가 종종 있어요.
Get started 들어가 봤는데 기초 사용법 튜토리얼 이라고 표시된게 10페이지 짜리 문서면 너무 싫습니다.
잘 만든 튜토리얼의 사례로 장고도 있습니다 https://docs.djangoproject.com/en/5.1/intro/tutorial01/