Tony Ibbs는 Aiven에서 개발자 교육을 담당하고 있습니다. Aiven는 오픈 소스 클라우드 데이터 플랫폼이라고 하네요. 국내에는 잘 알려지지 않은(검색해 보았을 때) 핀란드 회사입니다. 작년 프라하 컨퍼런스에서는 세션은 담당하지 않고 라이트닝 토크에서 아포스트로피 사용에 대한 짧은 이야기를 전했었네요.
슬라이드를 공개해놓았습니다. 뭐 길지 않은 슬라이드이긴 하지만 ^^
https://github.com/tibs/beyond-spellchecking-talk
문서를 검토하는 가장 좋은 방법은 동료 검토자가 있어서 검토를 요청할 수 있는 것입니다. 하지만 그렇지 않은 경우가 많죠. 조직 내에서 혼자만 문서 업무를 담당하고 있을 수 있고 검토 요청을 하기에는 다들 서로 바쁜 경우엔 그렇죠. 그래서 그런 경우에 사용할 수 있는 도구(Lint)에 대한 설명으로 시작합니다.
lint 또는 linter의 어원에서부터 설명하는데요. lint는 보풀을 의미합니다. lint 툴은 보풀을 제거하는 것처럼 코드 상에서 불필요한 부분을 제거해주는 역할을 하는 것이죠. 정확하게는 lint remover가 맞는 의미일 것 같습니다만 처음 만들 때 그냥 lint라고 정한 것 같네요.
프로그래밍에서는 규칙이 제한되어 있어서 이런 것을 적용하기가 상대적으로 좋은데 구문 언어는 그렇지 않습니다. 좀 더 범위가 넓고 다양한 변이가 발생하기 때문이죠.
그럼에도 광범위하게 쓰이는 Lint 규칙이 있고(구글이나 마이크로소프트에서 사용하는) 그 외에 조직 사정에 맞게 규칙을 추가해서 사용할 수 있다는 조언입니다. Aiven에서는 이런 이런 것들을 체크한다고 설명하구요. 인상적인 부분은 특정 팀원이 잘 틀리는 규칙을 추가해놓고 쓰다가 나중에 그 팀원이 퇴사를 하면 규칙을 빼야 한다고 합니다. 규칙이 계속 누적되면 어찌 되었든 부하가 되기 때문이죠.
코드와 다르게 문서화에서 Lint는 사람의 개입(확인)이 필요하다고 합니다. 그래서 명확한 에러만 자동으로 처리하고 애매하거나 확인이 필요한 것은 경고로 처리해서 확인할 수 있게 합니다.
여러가지 Lint 도구를 소개해주었는데 주로 영어권에 맞게 되어 있어서 한국어에는 적합한 툴이 아직은 없습니다. 몇 번의 시도는 있었던 것 같지만 대중적으로 확산된 도구는 없는 듯합니다.
https://github.com/tibs/beyond-spellchecking-talk#links-mentioned-in-the-slides
Aiven에서는 Vale을 사용하는데 문서화에 사용하는 코드가 공개되어 있어서 그 내용을 확인할 수 있습니다. CI에서는 vale-action을 사용한다고 합니다.
https://github.com/aiven/devportal
Tibs
Explore writethedocs' photos on Flickr. writethedocs has uploaded 2656 photos to Flickr.
www.flickr.com
