기술 문서 작성을 위한 초안 만들기

이전글 보러가기 >> 2024.01.14 - [Read] - 기술 문서 작성을 위한 문서 유형

🐾들어가며

Docs for Developers 의 chapter 3 문서 초안 만들기를 읽고 정리하였습니다.
다루는 주제는 아래와 같습니다.

1. 도구 선택
2. 개요 작성
3. 초안 작성
   • 초안을 작성할 때
   • 작성이 막혔을 때
   • 템플릿으로 작성하기

책에서는 순서를 부여하지 않았지만, 저는 단계별로 있는 게 이해하기 쉬워서 순서 목록으로 작성했습니다! 그러다보니 리스트 형태로 정리했는데, 각 단계별로 생각할 점을 체크 리스트로 만들어 보는 것도 좋을 듯 합니다.

읽은 내용을 정리하는 것이기에 최대한 사견을 빼고, 제 것으로 만들기 위해 이해한 대로 순서를 재배치하면서 정리했습니다. 평소 생각하지 못했던 것들은 인용구로 강조하여 적었습니다.

✨본격적으로

✅1. 도구 선택

도구를 선택하는 데 시간을 너무 지체하지 마라. 대부분의 경우 기존 워크플로로도 충분하다.

도구를 선택할 때 고려할 점

• 최종 콘텐츠의 포맷
• 초안의 공유 가능 여부

제목을 작성할 때 고려할 점

• 문서의 목표를 한 가지로 제한하자.
• 독자, 목적, 콘텐츠 패턴을 먼저 정의하자.
• 제목은 읽는 목적을 요약한 것이다.

✅2. 개요 작성

문서의 개요는 문서에 대한 나만의 접근 방식을 빨리 검증할 수 있는 방법이다.

개요를 작성할 때 고려할 점

• 독자가 알아야 하는 것과 해야 하는 것이 무엇인지 생각해보기
• 처음 작성한 개요를 '독자를 어떻게 가장 잘 도울 수 있는지’에 집중하면서 재배치해보기

개요를 완성할 때 질문해보기

• 독자가 알아야 할 추가적인 소개 정보나 설정 정보가 있는가?
• 건너뛰거나 완전히 설명되지 않은 단계가 있는가?
• 단계들을 연속된 순서로 봤을 때 잘 이해가 되는가?

✅3-1. 초안을 작성할 때

초안의 주안점은 개요에 설명된 주제에 따라 독자를 안내하면서 독자가 필요로 하는 자세한 정보로 각 주제를 확장하는 것이다.

제목을 작성할 때

• 최대한 간결하고 명확하고 구체적이어야 한다.
• 가장 중요한 정보를 앞에 배치한다.
• 각 절에 대해 고유한 제목을 사용한다.
• 일관성을 유지한다.

단락을 작성할 때

단락을 작성할 때는 독자에게 그들이 이해하고 행동해야 하는 맥락을 제공하되, 간결하게 유지해라. 가능하면 단락은 문장 5개를 넘지 않도록 구성하자. 모바일 기기에서 읽기 더 쉽다.

• 절차를 언제 수행 해야 하는 지에 대한 맥락 제시
• 절차가 어떻게 작동하는 지에 대한 세부 사항 제공

절차를 작성할 때

• 절차를 작성할 때 시스템의 시작 상태를 확인하자. (로그인 상태, 타이핑 위치 등)
• 절차의 각 단계에는 한 가지 동작만 나와야 한다.
• 독자에게 그들이 절차를 제대로 완료했음을 확인하기 위한 방법을 제공하자.

목록을 작성할 때

• 사용자에게 가장 도움이 되는 방식으로 나열하자.
• 항목이 10개가 넘는다면 더 적은 항목으로 나누자.
• 각각을 제목과 단락으로 묶어서 구성해 보자.

초안을 작성할 때

• 가장 중요한 정보를 먼저 제시하자.
• 분량이 많은 텍스트는 최대한 나누자.
• 단순함과 명확함을 추구하자.
• 문서를 작성하는 목적을 잊지 말자!

이 콘텐츠가 독자의 니즈를 충족하는가?

✅3-2. 작성이 막혔을 때

콘텐츠가 완벽해야 한다는 생각을 놓고, 문법에 대한 걱정을 멈추고, 아이디어를 페이지에 적는데 집중하자.

• 완벽함을 내려놓자.
• 도움을 청하자.
• 누락된 내용은 표시하자.
• 꼭 순서대로 작성할 필요는 없다.
• 작성 수단을 바꿔 보자.

내용의 공백, 즉 중요한 정보가 누락된 부분을 발견하면 이를 표시해 두고, 확실히 채울 수 있는 부분에 대해 작업을 계속하자. ( … ) 처음부터 문서를 정확하고 순서에 맞게 작성하는 데 매달리지 말자.

✅3-3. 템플릿으로 작성하기

템플릿은 일관성 있는 문서를 생성하고 향후 문서 생성을 간소화하는 안정적인 방법입니다. 다만, 내용이 독특하거나 맥락이나 이야기에 중점을 둔 문서를 템플릿화하는 것은 좋지 않습니다.

✅초안을 완성할 때

초안 완료 여부 확인을 위한 질문 리스트

• 문서 제목에 문서의 목표가 요약되어 있는가?
• 섹션 제목들이 모여 문서를 적절히 요약하는가?
• 초안의 처음부터 끝까지 독자의 니즈를 다루는가?
• 정보의 흐름이 독자가 이해하기에 적절한가?
• 초안이 마찰 로그에서 찾아낸 문제를 다루는가?
• 초안이 문서화 패턴이나 템플릿을 올바르게 따르고 있는가?
• 절차 일부 또는 전체가 작동하는지 테스트하고 확인했는가?

✔️결론

요즘 사이드 프로젝트와 관련하여 책집필을 준비하고 있습니다. 아직 경력도 없지만 최대한 경험했던 내용들에 대해 문제를 찾고, 비슷한 경험을 하거나 아직 시도하지 못한 분들을 위해 책을 쓰고 있습니다. 그리고 책을 쓸 때 다같이 쓰고 있는데, 코드 작성할 때처럼 제각각이라 컨벤션을 정하는 일이 걱정입니다. 어떤 게 가장 최선일지를 고민하게 되는 일인 듯 합니다.

이번에 이 챕터를 컨벤션을 정하기 전에 읽어서 다행이라고 생각합니다. 기술 문서이지만, 책을 쓸 때도 비슷하게 적용하고 싶은 내용들이 많았고, 공유하고 싶은 내용들이었습니다. 그래서 리스트 형태로 적은 이유도 생각할 포인트를 명확히 짚어주고 싶었습니다. 맥락 상에서 읽어야 좋은 형태인 것도 있지만, 저도 이 글을 다시 보면서 글을 쓸 때 아주 많이 참고할 듯 하여 최대한 간결하게 적어보았습니다.

정리하자면,

어떤 독자를 위해, 어떤 목표를 수행하기 위해 글을 적는가라는 질문을 계속해서 상기하면서 글의 '완성’이 아닌 '완료’에 초점을 두어 작성하자!

많은 리스트가 있어도 이 글에서 제가 읽은 가장 중요한 내용으로 가지고 가고 싶었습니다.

이 글은 옵시디언을 통해 발행하였습니다.