문서화에서 놓쳤던 몇 가지 부분들

개요

최근 도커 배포 가이드 문서를 작업할 일이 있었다(기회가 된다면 개인 환경에서 해보고 블로그에 올려도 좋을 듯 하다). 

작업을 마친 후 같은 팀 동료 한 분께 리뷰를 부탁드렸는데 스스로 작성했으면서도 깜짝 놀란 요소가 몇 가지 있었다.

 

 

---

문제

1. 용어를 혼용한다

생각보다 표현 과정에서 여러 단어를 쓰고 있었다.

가령 도커 허브 같은 단어를 저장소 혹은 레포지토리라고 쓰는 등이다.

아마도 헬름이나 깃허브 때문에 저장소나 레포지토리라는 단어가 익숙해서 무의식적으로 함께 쓴 듯 했다.

읽는 입장에서는 확실히 혼란스러울 법한 표현이었다.

 

만일 해당 환경에 어느 정도 익숙하다면 큰 문제가 없겠으나,

문서화는 당장 인수인계서로 써도 손색이 없을 정도로 작성해야 한다고 생각하는 편이었는데도 스스로 단어들을 섞어서 읽는 사람을 혼란스럽게 만들고 있었다는 사실은 조금 충격이었다.

 

 

 

2. 정확하지 않은 동사로 설명하려 한다

찌르다, 말다, 집어넣다... 같은 단어를 생각보다 많이 쓰고 있었다.

이런 표현의 안 좋은 점은 새로 배우는 단계의 사람들에게 정석적인 표현(요청을 보내다, 빌드하다, 삽입하다 저장하다 등등)을 인지할 기회를 주지 않아 자료를 찾아볼 때 검색하는 방식에 애를 먹거나 다른 사람과 소통할 때 모호한 단어로 하게끔 유도하기 때문이다.

 

 

 

3. 설명을 생략한다

과정에 대한 설명만 진행하고 몇몇 용어에 대해서는 설명을 건너뛰는 경우가 많았다.

배포 과정에 대해서만 설명하며 컨테이너나 Dockerfile의 동작 방식 등등에 대해서는 설명하지 않는 등이었다.

이런 건 사실 직접 설명하지 않고 하이퍼링크로 연결하여 사전적 의미만 전달되어도 읽는 입장에서는 이해가 잘 될텐데

다시 보니 아쉬운 점이 좀 있었다.

 

 

---

어떻게 하면 좋을까?

문서화는 쓰는 입장에서 작성이 되어서는 안 된다. 읽는 사람의 이해를 돕겠다는 관점에서 작성되어야 한다.

1번, 2번의 경우 용어를 단일로 통일하거나 하단에서 서술할 때 사용할 단어를 한정짓는 게 도움이 될 수 있을 것이다.

3번의 경우는 혼자서는 눈치채기 힘들다. 다른 사람에게 문서가 어떤 지 물어볼 수도 있을 것이고,

스스로 퇴고하는 게 도움이 될 수도 있을 것 같다.

 

---

그렇게까지 해야하나?

라고 할 만도 한게, 상기의 요소들은 조금 깐깐한 부류에 해당한다.

내가 말하는 이야기는 어느 정도 문서화가 이뤄진 상태에서 할 법한 좀 더 나은 문서 작성법이 있지 않을까 하는 것이다.

나는 굳이 쓸 거라면 상대방이 읽는 동안에 들이는 리소스를 최대한 줄이고 놓치기 쉬운 요소들은 다 챙겨야한다고 보고,

그게 종합적으로는 인수인계나 공유에 들어가는 시간과 자원을 줄여준다고 믿고 있다.

 

만일 문서를 읽었음에도 놓친 내용이 있거나 이해하지 못한 내용이 있어 결국 사람이 다시 설명해야 한다면

그건 문서가 책임을 다하지 못한 게 아닐까...라는 생각이 든다.

 

인수인계를 할 때 '아~ 그건 이 문서 보시면 돼요!' 라고 퉁치는 경우가 많은 것을 생각하면 더욱 그렇다.

여전히 궁금한 점이 남은 채로 사람을 통해서 물어봐야 하는 문서는 아쉬운 점이 있다.

만일 정말로 문서가 잘 관리되고 또 공유된다면 덧붙여 내용이 좀 더 잘 짜면 문서만으로 충분하지 않을까...

 

 

---

 

개인적인 문서 작성법

개인적으로 문서를 작성할 때 챙기는 몇 가지 요소가 있다.

 

 

 

1. 이 문서가 무엇을 위해 있는지와 어떻게 봐야하는 지를 설명한다

문서 상단에는 이 문서를 작성한 이유를 설명한다. 콜아웃이어도 좋은 것 같고, 그냥 개요에 적어도 좋은 것 같다.

이런 걸 적어주는 건 사실 흥미를 돋우는 용도가 가장 크다.

회사에 막 입사하면 사내 노션이나 컨플루언서 등에 올라온 문서를 읽어보라는 이야기를 듣는데,

사용하지 않거나 업데이트가 안 된 지 오래 된 문서도 많고, 일단 무엇보다 읽다보면 흥미가 죽는다.

 

개요나 콜아웃 등에 정보를 명시해주면 읽는 사람은 이 문서가 당장 필요한지, 혹은 천천히 살펴봐야 하는지 알 수 있고, 

이 문서가 제공하는 정보에 대해서도 전문을 읽어보지 않고 직관적으로 파악할 수 있다.

또한 얻을 수 있는 정보가 사전에 명시되므로 읽는 사람으로 하여금 흥미를 유도하기에도 좋다.

 

추가로 특정 목차를 봐야하는 경우나, 내부 시스템에서 적용된 사항, 참고하기 좋은 레퍼런스를 명시해주는 것도

읽는 사람이 필요한 부분을 취하게 하기에 나쁘지 않은 것 같다.

 

 

2. 이점을 설명한다

1번과 연결되는 내용이다. 특정 기술과 어떤 프로세스에 대해 설명할 경우 가급적 이점을 설명하는 편이다.

읽는 사람으로 하여금 흥미를 생기게 하는 것도 의의이지만 왜 쓰고 있는지를 피력하는 것도 중요하다고 본다.

 

새로운 사람의 입장에서는 당혹스럽거나 왜 이런 프로세스를 유지하고 있는지 의문을 가질 수 있기 때문이다.

읽는 사람이 당위를 이해하면 프로세스에 대한 이해도가 높아지게 된다.

가장 좋은 경우는 다른 사람들이 해당 프로세스를 개선할 여지를 줄 수 있다는 점에도 있다.

 

 

3. 이미지나 예시를 통해 이해를 돕는다

비교할 수 있는 사진을 제공하면 더더욱 좋다.

만일 해당 환경에 대해 이해하지 못하더라도 비교하며 작업을 진행하는 게 가능하기 때문이다.

특히 가이드 문서의 경우 참고할 만한 레퍼런스를 꼭 함께 적어주는 편이다.

 

 

4. 할 수 있는 실수와 해결 방법을 유도한다

놓치기 쉬운 부분은 콜아웃 혹은 색상을 구분해 명시하고 해결 방법을 같이 적어준다.

단순하게 A를 하고 B를 하세요, 라고 명시하며 C를 하지 말라고 가이드해주면 하기 쉬운 실수를 줄일 수 있다.

 

 

 

5. 참고할 레퍼런스와 문의하기 좋은 사람을 명시한다

공식, 혹은 번역 문서나 잘 가이드된 블로그 등을 써주면 읽는 사람이 이 주제에 관해 더 살펴보고 싶을 때

도움을 받을 수 있다.

 

문의하기 좋은 사람을 명시하면 주제에 대해 물어볼 수도 있고,

문서에 대한 유지보수가 해이해지더라도 나중에 리마인딩을 받을 수 있으므로

좀 더 유지보수하기 쉬운 환경을 작성자에게도 만들어줄 수 있는 것 같다.