Sarah Rainsberger는 오픈소스 프로젝트 astro의 문서 작성 책임자입니다. astro에 합류하기 전에는 교육계에서 일했다고 합니다. 과외 같은 수업도 진행했는데 커뮤니티 주도로 문서를 작성하는 astro에서는 그런 역할이 필요했나 봅니다. 가이드를 제공하고 작성한 글을 첨삭해 주는 역할입니다.
https://docs.astro.build/en/getting-started/
문서가 기술적으로 정확한 것만으로는 충분하지 않습니다.
문서는 커뮤니티의 요구를 충족시켜야 합니다.
astro는 커뮤니티 주도로 문서를 작성합니다. 여기에는 3가지 원칙이 있습니다. 협업, 적용, 참여입니다.
- 협업
깃헙을 통해 문서 소스 코드를 공개하고 문서화 프로세스를 확인할 수 있습니다. 그리고 어느 정도 문서화가 진행되고 있는지도 누구나 확인할 수 있습니다.
- 적용
적절한 질문을 통해 사용자의 요구사항을 이끌어냅니다. 그리고 이를 바탕으로 문서를 지속적으로 개선합니다.
이 문서가 여러분의 질문에 대한 답변을 얼마나 잘 해주었나요?
문서에 어떤 내용을 추가하면 도움이 될까요?
문서 사이트 어디에서 이 정보를 찾을 수 있을 것이라 예상했나요?
- 참여
누구나 참여할 수 있게 장벽을 낮춥니다. 프로세스가 빠르게 동작해 내가 참여한 결과를 오래 기다리지 않고 확인하게 합니다.
관리적인 측면에서 하나의 독립된 주제를 각 관리자가 담당하게 합니다. 그래야 좀 더 빠르게 프로세스가 동작할 수 있습니다. 사소한 오타보다는 명백한 오류를 우선순위에 두고 수정합니다. 독자가 문서를 읽고 제품을 사용하는데 방해가 되는 것이 우선순위에 놓고 작업해야 할 대상입니다.
PR에 대해서도 제목과 내용을 좀 더 쉽게 검색하고 이해할 수 있게 수정할 수 있습니다. 작업에 따라 PR을 분할하거나 추가적인 작업을 지정할 수도 있습니다.
부정적인 피드백을 주어야 할 때 사용할 수 있는 몇 가지 팁이 있습니다.
(이건 문화적인 차이도 있을 수 있으니)
"일관성을 유지하기 위해..."
작성한 내용 중 수정이 필요한 경우에 사용합니다.
"고마워요, 몇 가지 제안을 받아들였는데 잘 작동할 것 같아요!"
PR에 여러가지 항목이 포함된 경우 모든 것을 다 받아들일 필요는 없습니다.
"멋진 블로그 게시물이 될 것 같아요!"
사용자 문서에는 적합하지 않지만 좋은 팁이 될만한 글을 어떻게 활용할지 가이드해 줍니다.
"이 페이지는 아직 검토 예정이 없습니다..."
아. 이건 좀 애매할 수 있겠네요.
Q&A
Q: PR 처리가 지연되고 있다면 어떻게 대응하나요?
A: 다들 바쁘기 때문에 그럴 수 있습니다. 디스코드 채팅을 통해 추가적으로 커뮤니케이션이 필요한 경우 대응하고 빠르게 처리할 수 있게 안내합니다.
구글 Season of Docs 같은 행사에서도 문서화를 위해 참여한 인력들은 주어진 기간 동안 열심히 하는데 이를 리뷰해 주고 PR을 처리할 사람들의 일정을 맞추지 못하다 보니 일부 작업이 지연되는 상황도 있었다고 합니다. 아마 비슷한 이야기 같네요. 이런 작업을 조정해 주고 응원해 주는 역할만으로 관리자의 역할은 벅찰 것 같네요.
https://developers.google.com/season-of-docs
Sarah - Happy Contributors, High Standards, pick two! Balancing quality and community in open source documentation
www.flickr.com
