- 효과적인 검토 전략:
좋은 문서와 효과적인 리뷰는 함께 진행되어야 합니다.
문서 작성자가 문서 작성을 쉽게 시작할 수 있도록 모범 사례와 구조화된 프레임워크를 지원합니다.
리뷰는 문서 작성자의 기술 수준이나 문서화 프로세스에 대한 이해도에 따라 맞춤형 피드백을 제공해야 합니다.
- 엔지니어의 글쓰기 장려
엔지니어는 기술적 정확성을 기반으로 탄탄한 문서를 작성할 수 있습니다.
구조화된 템플릿과 지침을 제공하고, 테크니컬 라이터가 콘텐츠를 다듬고 개선하면 엔지니어가 효과적으로 문서화에 기여할 수 있습니다.
- 문서의 유형 및 작성자의 역할:
엔지니어는 빠르게 바뀌는 세부적인 문서(예: 참조 문서)를 작성하는 데 탁월합니다.
테크니컬 라이터는 명확성, 스토리텔링, 콘텐츠 구조화(예: 설명서)에 중점을 둡니다.
또한 테크니컬 라이터는 조직의 문서 전반에 걸쳐 일관성을 유지합니다.
- 피드백의 심리적 안전:
리뷰는 긍정적인 환경을 조성하여 문서 작성자를 무능하다고 느끼지 않고 격려해야 합니다.
문서 작성자를 존중하며, 건설적이고 구체적인 피드백을 통해 참여를 독려하고 문서 작성 품질을 향상할 수 있습니다.
- 모범 사례를 검토하세요:
변경 사항을 추적하는 대신 댓글을 사용하고, 피드백이 필요한 특정 영역을 강조 표시하고, 댓글당 하나의 아이디어로 제한하고, 작성자가 응답하도록 장려하세요.
검토 프로세스 초기에 참여하고 마감일을 정하면 더 나은 결과를 얻을 수 있습니다.
이런 지침 관련해서 발표 자료에는 아래 링크를 보여주었는데 해당 링크는 연결이 되지 않네요.
https://www.thegooddocsproject.dev/tactic/commenting-guide
아마 아래 링크가 적절한 내용인 것 같습니다.
https://gitlab.com/tgdp/templates/-/issues/378
https://gitlab.com/tgdp/governance/-/blob/main/DocCommentingGuide.md
문서 작성이 끝날 때까지 기다리지 말고 중간 중간 피드백을 주는 것이 좋습니다.
예를 들어 문서 작성에 2주가 걸리는데 2주 후에 피드백을 주면 2주 전에 어떤 생각으로 문서를 작성했는지 명확하지 않을 수 있습니다.
https://youtu.be/dH3hDuhh5Wg?si=X77mY34-Ee-Sh9cB
Write The Docs 2024 - Cameron Shorter
www.flickr.com
