IT/모바일
프로젝트를 설명하는 다양한 기술 문서는 개발자 경험을 향상시키고 제품의 채택률을 높이며 고객 지원 비용을 낮춥니다. 장기적으로는 제품의 평판을 높이고 경쟁 우위를 제공하여 사업 성공에 중요한 역할을 합니다. 이는 실제로 오랫동안 사업을 성공적으로 이끌어 온 많은 기업에서 증명된 바 있습니다.
하지만 '좋은' 기술 문서는 쉽게 만나보기 어렵습니다. 내용을 처음 접하는 사람에게 프로젝트의 A부터 Z까지 알고 있는 담당자의 시선에서 작성된 문서는 너무나 어렵기 때문입니다. 그럼 모두에게 쉬운 기술 문서는 어떻게 작성해야 할까요?
오늘은 리눅스 재단, 구글, 스트라이프, 론치다클리, 영국 정부와 같은 곳에서 기술 프로젝트를 문서화하는 일을 한 사람들이 알려주는 기술 문서 작성의 단계별 프로세스를 소개합니다.
1. 독자 이해하기
효과적인 문서화를 위해서는 사용자에 대한 공감이 필요합니다. 인터뷰, 개발자 설문 조사, 고객 지원 문제 검토와 같은 사용자 조사 및 도구를 사용하여 공감을 쌓을 수 있습니다. 그런다음 조사 내용을 압축하여 이후 단계에서 참고할 수 있는 사용자 페르소나, 사용자 스토리, 사용자 여정 지도를 만드세요.
사용자의 입장이 되어 소프트웨어 사용에 방해되는 마찰 요소를 직접 경험한 후 마찰 로그를 작성하는 것도 좋은 공감 방법입니다.
<마찰 로그 예시>
2. 문서화 계획하기
사용자 이해를 모두 마쳤다면 문서화 계획을 통해 행동으로 옮길 차례입니다. 문서화 계획은 만들어야 하는 콘텐츠 및 콘텐츠 유형을 문서 작성에 앞서 간략하게 설명하는 문서입니다.
콘텐츠 유형은 정보를 제시하는 다양한 방법입니다. 서로 다른 콘텐츠 유형은 다양한 종류의 문제를 해결하는 데 도움을 주죠. 콘텐츠 유형에는 코드 주석, READEME, 시작하기 문서, 개념 문서, 절차 문서 및 참조문서 등이 포함됩니다. 이러한 각 유형은 서로 다른 패턴을 따르는데, 이러한 패턴을 기반으로 콘텐츠를 구축하면 효과적이고 일관성 있는 문서를 작성할 수 있습니다.
문서화 계획은 사용자가 필요로 하는 콘텐츠의 유연한 밑그림 역할을 하며 여러분이 가장 중요한 문서를 작성하는 데 집중할 수 있도록 해 줍니다.
3. 문서 초안 만들기
이제 본격적인 문서 작성에 돌입할 차례입니다. 메모장도 좋아요. 편안하고 친숙한 문서 작성 도구를 실행시켜 주세요. 코드 작성에 사용하는 툴체인은 문서화에 활용하기에도 좋습니다. 문서를 작성할 땐 이런 점에 유의해서 작성해 보세요.
① 문서의 목표는 제목에서 드러나야 합니다.
문서의 대상, 목적, 패턴을 정의하는 것으로 시작하세요. 가령, 문서 내용이 '성공적인 기술 문서 작성 방법을 설명하기'라면 제목을 <기술 문서 작성 완벽 가이드>라고 적어보세요. 내용을 보지 않아도 빠르게 문서의 목표를 파악할 수 있습니다.
② 문서 초안을 작성하세요.
문서의 개요를 만들고 제목, 단락, 목록, 안내 문구를 사용하여 내용을 구체화합니다. 문서화 계획의 세부 사항도 꼭 채워 넣어주세요.
③ 가장 중요한 정보는 먼저 제시해주세요.
독자가 내용을 확인하는 방법을 고려해 문서를 작성합니다. 독자는 문서를 훑어볼 것이므로 가장 중요한 정보를 먼저 제시하고 독자를 위해 내용을 나누어 정보를 쉽게 찾을 수 있도록 합니다.
4. 문서 편집하기
문서 초안 작성이 모든 아이디어를 써내려가는 일이라면, 문서 편집은 코드를 테스트하고 리팩터링하는 것과 유사하며 그만큼이나 중요합니다. 문서를 살펴보며 사용자의 니즈를 충족하도록 수정하고, 텍스트가 최대한 명확하고 빠르며 유용하게 사용자에게 정보를 전달하는지 꼼꼼히 들여다봐야 합니다.
이후 여러 동료들과의 협업을 통해 검토를 진행합니다. 피드백을 제공할 때는 건설적인 제안을 더하는 경우에만 아이디어를 비판하세요. 좋다고 생각하는 점에도 피드백을 남겨야 합니다.
샘플 코드는 개발자 문서에서 결정적인 역할을 하는 부분입니다. 텍스트와 코드는 서로 다른 언어이며, 문서의 독자인 개발자가 궁극적으로 관심을 갖는 것은 코드입니다. 단어로 아무리 명확하고 아름답게 표현하더라도 독자가 개발을 시작하는 데 도움을 주거나 특정 기능의 사용 방법을 보여주는 데는 잘 만들어진 샘플 코드보다 좋은 것은 없습니다.
좋은 샘플 코드는 그것을 설명하는 글보다 더 많은 내용을 전달하는 동시에, 독자들이 참고하여 코드 작성의 기반으로 삼을 만한 유용한 틀을 제공할 수 있습니다.
문서에서 샘플 코드를 제공한다면 다음과 같은지 꼭 확인하세요.
① 설명 제공 : 샘플 코드 이면의 정보 제공하기
② 간결함 : 사용자가 재현할 수 있는 최소한의 예제 제공
③ 명확함 : 기존 규칙 및 스타일 가이드 따르기
④ 확장 가능함 : 독자가 자신의 코드를 수정해야 하는 위치와 방법을 명확히 안내
⑤ 신뢰할 수 있음 : 일관성을 확보하여 독자와 신뢰 쌓기
6. 문서 이해를 돕는 요소 추가하기
'백 마디 말보다 한 장의 그림이 낫다'라는 표현이 있을 것입니다. 인간의 뇌가 이미지 한 개를 처리하는 데 보통 0.013초가 소요됩니다. 이미지를 하나씩 제공하면 인지 처리가 덜 필요하고, 두뇌가 연결 관계를 도출하는 데 도움이 되며 텍스트보다 훨씬 빨리 이해를 이끌어 낼 수 있습니다.
다만, 이미지와 텍스트가 서로를 잘 보완하는지 확인하세요. 문서에 포함되는 여러 이미지는 다이어그램, 레이블, 색상을 모두 일관성 있게 사용해야 합니다. 시각적 콘텐츠를 사용할 때는 항상 세 가지 원칙을 항상 마음에 새기세요.
① 이해 용이성 : 이 콘텐츠가 독자에게 도움이 되는가?
② 접근성 : 일부 독자에게 사용하기 어렵지는 않은가?
③ 성능 : 콘텐츠의 크기와 포맷이 독자에게 도움이 되는가 아니면 방해가 되는가?
이제 우리는 사용자의 니즈를 파악하고 문서화 계획을 세운 뒤 초안과 편집 작업까지 모두 마쳤습니다. 프로젝트를 가장 잘 설명해주는 이 기술 문서를 어떻게 독자들에게 효과적으로 배포하고 유지, 관리할 수 있을까요?
소프트웨어 엔지니어는 물론 프로덕트 매니저, 기술 블로그 운영자, 테크니컬 라이터 등 다양한 테크 콘텐츠를 작성하는 모든 사람을 위한 기술 문서 작성 방법은 <Docs for Developers 기술 문서 작성 완벽 가이드>에서 더욱 자세히 확인할 수 있습니다.
<Docs for Developers 기술 문서 작성 완벽 가이드>
자레드 바티 , 재커리 사라 콜라이센 , 젠 램본 , 데이비드 누네즈 , 하이디 워터하우스 저 / 하성창 역
소프트웨어 개발자를 안내하는 테크니컬 라이팅을 위한 실무 노트
우아한형제들, 카카오엔터프라이즈, AWS, LINE Plus, 쿠팡, 넷마블 등 국내 테크니컬 라이터 11인 인터뷰 특별 수록!
이 책은 ‘강아지 음성 번역 서비스’를 만드는 개발 팀의 스토리를 따라가며, 개발 문서를 만드는 과정을 단계별로 배우도록 구성되었습니다. 단계별 예제, 템플릿, 가이드를 통해 이론적인 내용뿐만 아니라 문서를 효과적으로 작성하고 관리하는 방법도 배우게 됩니다. 단계에 맞는 문서화 기술을 배우고, 사용자 니즈 이해부터 문서 작성, 유용한 개발자 문서 배포 및 유지까지 프로젝트 관리와와 소프트웨어 개발 라이프사이클 전체를 한 권에 담아 설명합니다.
또한 부록에는 우아한형제들, LINE Plus, 카카오엔터프라이즈, NHN 클라우드, 넷마블, 데브시스터즈, AWS, 쿠팡에서 활동하는 국내 유명 테크니컬 라이터 11인의 인터뷰가 수록되었습니다. 테크니컬 라이팅이 무엇인지, 업계에서 테크니컬 라이터의 역할에 대해 설명합니다. 이미 테크니컬 라이팅의 세계를 경험한 선배들의 다양한 경험과 이야기를 들을 수 있습니다.
최신 콘텐츠