https://news.hada.io/topic?id=18743
규칙
- 초보자를 위한 글쓰기
- 명확한 결과를 약속하는 제목 작성
- 도입부에서 목표 설명
- 최종 결과 미리 보여주기
- 복사/붙여넣기 가능한 코드 스니펫 작성
- 명령어에서 긴 플래그 사용
- 사용자 정의 값과 재사용 가능한 로직 분리
- 독자의 수고 줄이기
- 코드가 항상 작동 상태로 유지되도록 작성
- 하나의 주제만 가르치기
- 꾸미기보다 명확성 우선
- 종속성 최소화
- 파일 이름 명확히 지정
- 일관성 있고 설명적인 제목 사용
- 솔루션이 작동함을 입증
- 완전한 예제 연결
초보자를 위한 글쓰기
- 튜토리얼의 가장 흔한 실수는 초보자 수준의 개념을 전문가 수준의 용어로 설명하는 것. 대부분의 튜토리얼을 찾는 사람들은 초보자임.
- 프로그래밍에 초보자가 아닐 수도 있지만 배우고자 하는 도메인에는 초보자임
- 초보자를 대상으로 작성하며, 전문가 수준의 용어 사용을 지양함
- 어려운 용어를 피하고 독자가 이해할 수 있는 간단한 언어로 작성
- 예를 들어 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 브랜치로 나누어 독자가 각 단계를 따라갈 수 있도록 함