🚥 리뷰 전
아무리 개발자라도 코드만 작성하고 수정하는게 다가 아니다.
간단하게는 나랑 같이 일하는 동료 개발자를 위해 코드에 주석을 달아놔야 할 수 있고, 혹은 프론트 개발자에게 새로 만든 API를 소개하며 글로 설명해야 할 수 있다.
간단한 예시만 말했지만 중요한 건 개발자라도 문서를 작성할 때가 있다. 문제는 개발자는(나를 포함해서) 대부분 문서를 작성하는게 어색하다는 것! 😕
그래서 이번에는 개발자들이 기술 문서를 작성할 때 필요한 정보에 대해 책을 읽어 보았다.
📚 본격 리뷰
독자들은 여러분이 쓴 글을 매우 조금 읽습니다.
- 본문에 기술 문서 독자에 대한 내용 중
1. 독자 이해하기
- 다른 사람도 자신과 같은 지식을 갖고 있다는 인지적 편향을 지식의 저주 라고 함
- 누구나 나와 비슷하게 생각한다는 가정하에 코드를 설명하거나 업무를 주지 말 것
- 가장 먼저 사용자가 누구인지, 사용자가 달성하고자 하는 전반적인 목표가 무엇인지 생각하기
2. 문서화 계획하기
- README는 사용자가 이 코드가 왜 존재하고 어떤 문제를 해결하는데 도움이 되는지 알 수 있게 해주는 문서
- 튜토리얼이 학습에 초점을 맞춘다면 How-To 가이드는 사용자가 실제 코드를 구현하는 동작에 기반을 둠
- 릴리즈 노트는 변경된 사항들에 대해 맥락을 제공하는 문서 (어느 정도의 변경 사항을 명시해야 할지 고민)
3. 문서 초안 만들기
- 목표는 한 가지로만 제한하고 목표에 도달하기 위해 필요한 모든 단계를 생각하기
- 개요를 작성할 때는 모든 단계들에 대해 순서를 따지지 않고 작성
- 제목은 내용을 구조화 하는데 도움을 줄 뿐 아니라, 검색 엔진 최적화(SEO)에도 중요
- 독자들은 콘텐츠 페이지를 볼 때 일반적으로 'F' 패턴으로 콘텐츠를 훑어봄. 이는 제목과 부제를 찾기 위해 문서 상단을 두개의 수평선으로 가로질어 훑어본 다음 페이지를 아래로 훑어보는 것을 의미
5. 샘플 코드 통합하기
- 개발한 코드가 동작하는 샘플 코드를 간단하게 만들기
- 개발환경 혹은 상황에 따라 다르게 동작하는 코드인지 확인
6. 시각적 콘텐츠 추가하기
- 정보를 귀로 듣는 경우에는 약 10%만 기억하는 반면, 이미지와 함께 나온다면 65%를 기억함
- 스윔레인 다이어그램 은 프로세스 참여자나 특정 역할을 하는 개체가 여러 개 있을 경우 유용함
- 다이어그램당 하나의 아이디어만 설명
10. 문서 구조화하기
- 웹 구조로 문서를 구조화하면 서로 비계층적으로 연결되어 하나의 페이지에서 다른 페이지로 자유롭게 이동할 수 있음
➰ 리뷰 끝
중간에 문서 배포나 피드백에 대한 내용들은 약간 일반적인 내용들이라서 리뷰에선 제외했다.
이런 기술 문서를 주로 작성하는 직군을 테크니컬 라이터(Technical Writer)라고 하는데 처음 알았다. 이런 직무가 필요한 건 기술에 대한 내용을 누구나 잘 이해할 수 있게 만드는 문서 작성 능력이 필요하기 때문이라고 생각한다.
테크니컬 라이팅에 관심이 있는 건 아니지만, 당장에 프론트엔드 개발자와 일할 때 API 문서에 기술 내용을 명시적으로 드러낼 수 있는 방안을 생각해봐야겠다.
링크 : Docs for Developers
생각하면 복잡하니까 일단 해보자