튜토리얼과 하우투 문서을 비롯해 개발 과정에서 읽고 쓰는 문서에 대한 특성(학습 중심 - 이해 중심 - 문제 중심 - 정보 중심 관점을 소개합니다. 학습을 위해 유튜브에 설명 동영상도 올려놓았습니다. https://youtu.be/HHlBLV281r0

1. 개발 문서 이야기 – 튜토리얼
과 하우투 문서의 차이점은?
2019년 11월 02일
박재호(jrogue@gmail.com)

2. 참고 자료
• What nobody tells you about
documentation(https://www.divio.com/blog/documentation/)

3. 개발 문서는 한 종류가 아니다!
• 튜토리얼, 하우투, 설명서, 참조 문서
• 각각에 대한 특징을 알아야 문서를 제대로 작성할 수 있다!
• 각각 작성에 필요한 기술이 다르다는 사실에 주목

4. 네 가지 문서의 특징
• 정보 중심
• 동작 방식 기술
• 정확하고 완벽함
• 예) 백과 사전
• 이해 중심
• 배경 지식과 맥락 제공
• 예) 요리 역사서
• 목표 중심
• 특정 문제에 대한 해법
• 일련의 단계
• 예) 전문 요리책
• 학습 중심
• 신입 대상
• 예) 아이들용 요리책
튜토리얼 하우투
참조문서설명서

5. 튜토리얼
• 일련의 단계를 따라하면 프로젝트를 완성할 수 있다
• 선생님 관점에서 기술 → 지시에 따라 학생들은 과업을 완료할
수 있어야 한다
• 주의
• 이론적인 지식이 아니라 실질적인 지식이다
• 실천으로부터 배워야 한다
• 다양한 환경에서 동작 가능해야 한다 → 주기적으로 운영체제/개발환
경의 변화를 점검할 필요가 있다
• 꼭 필요한 지식만 담아야 한다 → 그렇지 않으면 주의가 분산됨

6. 하우투 문서
• 실제 세계의 문제를 해결하기 위해 필요한 단계를 알려준다
• 예) 3차원 데이터 집합을 어떻게 그래프로 표현할까?
• 기초적인 지식을 갖춘 독자를 대상으로 한다
• 주의
• what은 알고 있으나 how는 모르는 상황에 있는 독자를 대상으로 한다
• 순서대로 따라할 필요가 있는 일련의 단계를 포함해야 한다
• 실용적인 목표를 달성하기 위한 과정에 집중해야 한다
• 환경이나 구성에 따라 약간의 유연성을 허용해야 한다
• 튜토리얼과는 달리 완벽할 필요는 없다

7. 참조 문서
• 기반 동작 원리와 운영 방법을 기술적으로 설명한다
• 문서의 유일한 목표는: 기술
• 핵심 클래스, 함수, API 등등 코드와 밀접한 내용을 담는다
• 사용 예시를 포함할 수도 있지만, 기초 개념과 일반적인 작업에 대한
지침은 포함하지 않는다
• 주의
• 일관성 있게 기술해야 한다
• 설명, 토론, 지시, 의견 등을 포함하면 안 된다
• 정확해야 한다

8. 설명서
• 특정 주제에 대해 설명한다
• 상위 관점에서 바라보도록 도와준다
• 다른 사람의 의견을 담은 토론 형식도 가능하다
• 스택 오버플로우
• 주의
• 배경 지식과 맥락을 제공한다: 설계 결정, 역사적인 이유, 기술적인 제
약
• 대안과 옵션을 소개한다
• 다른 문서에 없는 설명을 포함한다

9. 정리