Daniele Procida는 DIVIO라는 앱 플랫폼 회사의 CCO(Chief collaboration officer)입니다.
CCO는 우리말로는 협업 관리자인데, 이게 무슨 협회도 있고 꽤 뭔가 움직임이 많네요.
주로 "조직의 협업 업무를 기획하고 촉진하고 평가하고 확산시켜 조직성과를 높이는 사람"의 역할을 한다고 합니다.
하여간 이 분은 사내 문서화뿐 아니라 오픈소스 진영의 문서화 작업에도 많이 참여하면서 경험한 이야기를 공유합니다.
Always complete, never finished
세션 제목은 조부모님이 물려주신 가구에 붙어있는 로고 문구라고 합니다.
구글에서 검색해보면 책장 쪽에서는 좀 유명한 브랜드인가 봅니다.
강연 내용은 뭔가 말은 많은데 요약해보면
불필요하고 쓸데없는 고통을 최소화하자는 것입니다.
문서화 작업 시에
내가 알고 있는 것을 문서로 만드는 것은 어렵지 않습니다.
하지만 무엇을 문서로 만들지 결정하는 건 어렵습니다.
복잡한 프로젝트라고 크게 계획을 잡지 말고
작은 단위의 계획을 잡고 반복적으로 수행하는 것을 권장합니다.
계획을 고민하는데 너무 많은 시간을 쓰지 않도록
예로 자신의 프로젝트를 들고 있는데
처음에는 간단한 README 파일에 문서화 프레임워크에 따라
작성했는데 나중에 양이 많아지면서 스핑크스 기반으로 전환했다고 하네요.
c-is-for-camera.readthedocs.io/
Home - C is for Camera
Next Get started
c-is-for-camera.readthedocs.io
pytest 문서 개선 사례 같은 경우 워낙 방대한 문서와 빠르게 진행되는 병합 과정 때문에 장기적인 계획을 가지고 진행하기에는 어려움이 있어서 작은 단위로 과업을 만들고 이슈를 처리했다고
github.com/pytest-dev/pytest/issues/8443
Documentation restructuring · Issue #8443 · pytest-dev/pytest
A complete restructuring of pytest's documentation in line with https://diataxis.fr. See pytest-dev email list discussion. Progress so far Renamed Install to Getting started; moved notes to ind...
github.com
QnA 세션에서 흥미로운 이야기가 나왔는데
조직에서 장기적인 계획을 요구한다면
- 그럴듯한 가짜 계획을 만들고 내부적으로는 작은 단위의 과업으로 진행하라고 합니다.
라고 쓰고 보니 예전에 "문서화에 대해 아무도 말해주지 않는 것들"라는 번역글이 꽤 많은 공감을 얻고 공유됐는데, 그 원문과 diataxis.fr/ 콘텐츠를 작성하신 분이군요. 어이쿠 ㅠㅠ
그냥 대충 듣고 별 내용 없다고 생각했는데, 사실 알고 보면 꽤 많은 경험을 통해 얻은 결론을 이야기해주는 건데 말이죠. 이 내용은 다시 맘먹고 들어 봐야겠네요.
lazygyu.net/blog/secrets_of_documentation
문서화에 대해 아무도 말해주지 않는 것들
이 글은 What nobody tells you about documentation 을 번역한 글입니다. 오타 및 오역 지적 환영합니다.
lazygyu.net
번역은 2019년 1월에 게시됐는데, 2018년 12월 시점 이미지는 아래에서 확인해볼 수 있습니다.
web.archive.org/web/20181216225659/www.divio.com/blog/documentation/
이때는 긴 블로그 글이었습니다.
지금은 아예 별도 문서로 분리해서 게시되고 있습니다.
그 사이에 내용이 많이 보완되었겠죠.
