Emilia Juda Özbay는 블룸버그 테크놀로지 엔지니어입니다. 사내 개발자를 위한 개발도구를 만들거나 지원하는 업무를 담당하고 있어 문서화 도구도 마찬가지입니다.
블룸버그 테크놀로지에서 기존 자바스크립트 기반 환경을 타입스크립트로 변경하기로 결정했습니다. 코드 전환은 물론 배포 환경까지 바뀌어야 하는 커다란 인프라 변경이었지요. 이왕 바꾸는 김에 문서화 시스템도 같이 변경하기로 하고 현재 시스템의 pain point 6가지를 조사합니다.
(정확하게는 조사한 건 아니고 이런 저런 자료들을 참고해서 6가지를 선정한 것 같습니다. 참고한 자료는 이런 것들입니다).
- Library Evaluation Rankings
자바스크립트 라이브러리 선택 시 어떤 것을 먼저 보는지에 대한 질문인데 1위가 Documentation 이었습니다.
https://2021.stateofjs.com/en-US/other-tools/#tool_evaluation_wins
- Software Documentation: The Practitioners’ Perspectives (Emad Aghajani)
ICSE(International Conference on Software Engineering) 2020에서 발표한 내용입니다. 146명의 실무자를 대상으로 조사한 결과를 발표했습니다. Emilia 의 발표에서 해당 페이퍼 내용 중 "Documentation issues that are relevant to practitioners, according to the results of Survey"라는 표를 중간중간에 인용하고 있습니다.
ICSE 2020은 원래 서울 개최 예정이었는데 코로나 사태로 일정이 한 달 연기되고 비대면으로 진행됐습니다. 음. 이 분도 한국에는 오지 않았겠네요.
https://dl.acm.org/doi/10.1145/3377811.3380405
https://emadpres.github.io/publications.html 에 가보면 좀 더 많은 글이 있는데 문서화 관련해서 아래 링크도 참고하세요.
Software Documentation: Automation and Challenges
https://www.inf.usi.ch/faculty/lanza/Downloads/PhD/Agha2020c.pdf
1. Lack of automated workflows
자동화된 워크플로우의 부족
- 반복되는 작업을 사람이 처리하고 있다면 가능한 작업은 자동화로 처리하라는 조언입니다.
* 자동화를 하기 위해서는 어느 정도 표준화가 필요한데 어떻게 보면 문서의 자유로움을 빼앗는 결과이기도 합니다. "반복적인"이라는 키워드가 해당되는 경우에만 자동화를 고민하는 것이 좋습니다.
2. Poor reproducibility of build errors
빌드 오류에 대한 낮은 재현성 문제
- 빌드 시점이 아니라 로컬에서 문서를 작성하는 중에 테스트하고 문제를 처리해야 한다는 조언입니다.
* 이건 자동화와 살짝 비교되는 부분인데 자동화로 처리할 경우에는 세밀한 부분을 체크하지 못할 수 있어서 그런 건 각자 알아서 하라는 것 같긴 합니다.
3. Documentation is not part of the software delivery lifecycle
문서화가 소프트웨어 개발 주기에 포함되지 않은 경우
- 문서가 변경되어야 하는 여러 시점이 있는데 프로세스 상에 있지 않다면 놓치기 쉽다는 조언입니다.
* 해결책에서 Make it visible이라고 했는데 이건 프로세스 상에서 작성한 문서를 미리 보고 문제를 찾을 수 있게 한다는 의미 같습니다. 스테이징 단계가 여기에 포함될 듯싶네요.
4. Lack of traceability
문서 변경(위치)을 추적하는 기능의 부족
- 문서 내 실제 소스 링크를 하는 방식
https://bloomberg.github.io/pasta-sourcemaps/index.html#parse
- 개발자에게 왜 문서를 소스와 같이 수정하지 않냐고 물어보면 개발자는 문서가 어디 있는지 몰라서 그렇다는 대답을 자주 한다고
* 조직의 성격이나 다루는 문서의 규모에 따라 다를 것 같습니다.
5. Lack of guidelines
문서 작성에 대한 가이드라인 부족
- 가끔 문서를 작성하는 이들이 참조할 수 있는 가이드 문서 필요
- 문서 작성 표준을 따른다면 별도의 가이드 문서 없이 적절한 표준을 안내해주는 것만으로 충분함
- 문서의 목표를 명확하게 해주는 것도 중요함
https://github.com/reactjs/reactjs.org/blob/main/CONTRIBUTING.md
...Its goal is to give the reader a feel for a typical React workflow rather than to explain fundamentals in detail...
6. Low task prioroty
문서화의 우선순위가 중요하게 취급되지 않음
- 문서의 배포뿐 아니라 유지보수의 중요성을 인식하지 못하는 경우가 많음
* 해결책은 문서의 가치를 증명하는 것인데, 이것 역시 하나로 딱 정의하기 어렵습니다.
그래서 해결책은...
실제 적용한 것들...
Emilia Juda Ozbay
Explore writethedocs' photos on Flickr. writethedocs has uploaded 2656 photos to Flickr.
www.flickr.com
