기술 문서 작성을 위한 편집 프로세스

🐾들어가며

Docs for Developers 의 chapter4 문서 편집하기를 읽고 정리했습니다.

이번 챕터에서는 문서 작성과 문서 검토를 분리하여 창작과 평가 과정을 분리하는 편집 프로세스를 만드는 것을 목표로 합니다.

✨본격적으로

✅편집에 대한 접근법

편집 단계에서 중점을 두어야 할 것은 다음의 4가지로, 각 단계마다 하나씩 점검해야 합니다. 한 번에 많이 하는 경우, 속도가 현저히 느려질 수 있기 때문입니다.

• 기술적 정확성
• 완전성
• 구조
• 명확성과 간결성

기술적 정확성을 위한 편집

• 누군가가 이 지시 사항을 따라가면 약속한 결과를 얻을 수 있는가?
• 혼동을 일으킬 수 있는 기술적인 은어나 용어가 있는가?
• 코드의 함수, 파라미터, 엔드포인트가 올바르게 명명되고 설명되었는가?

완전성을 위한 편집

• [TODO], [TBD(To Be Determined)]가 채워졌는지 확인하자.
• 특정 버전에만 적용되는 경우인지 명확히 표시하자.

완전성은 '모든 것’을 이야기한다는 의미가 아니다. (…) 완전한 문서는 문서가 필요한 사람들에게 도움을 주기에 충분한 정보를 포함하되, 그들이 원하는 것을 찾을 수 없을 정도로 지나치게 많은 정보를 포함하지는 않아야 한다.

구조 측면에서의 편집

• 문서 제목과 섹션 제목에서 문서가 무엇에 관한 것인지 명확히 드러나는가?
• 문서가 일관되고 논리적인 방식으로 구성되어 있는가?
• 문서에 다른 문서에 포함시키는 것이 더 적절한 섹션이 있는가?
• 템플릿이 있는 경우, 문서가 템플릿을 충실히 따르는가?

명확성과 간결성을 위한 편집

문서를 한 줄씩 검토하여 각 문장과 단락이 얼마나 이해하기 쉬운지 확인해야 한다.

• 최대한 명확하게 표현되었는가?
• 일관성 없이 사용되어 수정해야 할 용어가 있는가?
• 잘라낼 수 있는 불필요한 단어나 문구가 있는가?
• 독자를 혼란스럽게 할 수 있는 특정 표현, 비유, 속어가 있는가?
• 피해야 할 편향된 언어를 사용하고 있는가?

✅편집 프로세스 만들기

검토할 때 순서는 다음과 같습니다.

1. 작성한 문서 먼저 검토하기
2. 동료 검토 요청하기
3. 기술적 검토 요청하기

작성한 문서 먼저 검토하기

아래 체크리스트들을 참고로 하여 자신만의 편집 프로세스를 만들어봅시다.

• 편집 체크리스트
• 문서 제목이 짧고 구체적이다.
• 섹션 제목이 논리적인 순서로 배치되고 일관성이 있다.
• 문서의 목적이 첫 번째 단락에 설명되어 있다.
• 절차가 테스트되었고 잘 작동한다.
• 기술적 개념에 대한 설명이나 해당하는 링크를 제공한다.
• 문서가 템플릿의 구조를 따른다.
• 모든 링크가 작동한다.
• 맞춤법 및 문법 검사기를 실행했다.
• 그래픽과 이미지가 명확하고 유용하다.
• 모든 필수 조건과 다음 단계가 명시되어 있다.

동료 검토 요청하기

• 피드백을 받기 전 생각해보기
• 어떤 종류의 피드백을 원하는가? 구조적, 기술적, 명확성과 간결성?
• 어떤 방법으로 피드백을 받고 싶은가? 주석, 댓글, 메모?

기술적 검토 요청하기

기술적으로 이해한 바가 맞는지 다른 사람과 확인해야 한다.

• 두 가지 이상의 기술을 통합하는 경우, 각 전문가에게 요청하자.

✅피드백 받아서 반영하기

문서 검토는 개인의 흠을 들추려는 것이 아니라 콘텐츠를 개선하는 데 도움을 주기 위한 것임을 기억하자.

• 상반된 피드백을 받았을 경우, 다음과 같은 질문을 해보자.

이 문서의 사용자가 알아야 할 사항은 무엇인가?

✅좋은 피드백 제공하기

동료 검토는 '건설적인 태도’로 접근할 때 가장 효과적이다.

• 플러싱 규칙
  • 사람이 아니라 아이디어에 집중하기
  • 건설적인 제안 덧붙이기
  • 피드백을 받는 사람이 피드백에 반응할 시간 주기

우리가 무엇을 발견하든 우리는 모든 사람이 당시에 알고 있던 것, 그들의 기술과 능력, 사용 가능한 자원, 당면한 상황에서 최선을 다했다는 점을 이해하고 진정으로 믿습니다. - Norm Kerth

✔️결론

빨리 내용 정리하고 현재 하고 있는 책집필에 적용하기 위해 다이어그램을 그리러 가고 싶습니다! 잘 이해되지 않은 부분이 있다면 댓글로 알려주세요~! 감사합니다!

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