개발자가 문서화를 잘 하는 방법

in Etc / Think on 개발, 개발자, 문서화, 문서, Document

개발자에게 문서란 뭘까

문서를 마주하기

개발자들은 문서를 매일은 아니지만 자주 접하게 된다. 서비스 설계서, 화면 설계서 부터 산출물 보고서 나 개발 공식 문서까지 사람에 따라 다르겠지만 매번 다양한 종류의 문서를 접한다.

현업이나 기획자, 설계서는 회사마다, 부서마다, 사람마다 퀄리티의 차이가 있지만 보통 우리가 보는 공식 문서는 보는 입장에서는 상당히 잘 정리가 되어 있다.

아닌 케이스도 있겠지만 대부분의 공식 문서는 보기도 편하고, 깔끔하며 읽는 사람이 알기 쉽게 적혀져 있다.

그렇다면, 만약 당신이 그러한 문서를 작성하라 고 한다면? 저 정도의 퀄리티가 나올 수 있게 작성이 가능할까? 한 번쯤 그런 생각을 해보면 머리가 아찔하고 정말 그런 작업은 하기 싫다 라고 생각할 수 있다.

이 글을 읽는 당신도 혹시 그렇지 않은가?

문서화를 왜 해야 할까?

문서를 만드는 이유에는 여러가지가 있다. 다만, 여기서는 산출물이나 결과보고서 같은 정해진 양식이 있는 문서화를 제외한다. 이런 것들은 대부분 이미 양식이 정해져 있고, 들어가야할 내용도 정해진 기준이 존재하기 때문이다. 그 외에 문서화 하는 이유는 여태까지 많은 사례를 경험하지는 못했지만 적어도 내가 문서를 만들었던 상황은 다음과 같다.

  1. 머릿속 혹은 여러 곳에 흩어져있는 정보를 한 곳으로 모아 관리가 필요한 경우.
  2. 특정 업무/회의 등에 대한 요약이 필요하거나 기록하여 남겨야 하는 경우.
  3. 개발 소스 및 서비스 등 전반적인 개발 결과물에 대한 가이드가 필요한 경우.
  4. 특정 서비스, 사이트 이용, 아키텍처 등에 대한 가이드 제공이 필요한 경우.

이것 외에도 다양한 이유로 문서화를 진행해야 되는 경우가 있다.

그런 경우에 과연 어떻게 해야 문서를 잘 작성할 수 있을 것이며, 어떠한 노력을 해야 할까?

개발자가 문서화를 하는 상황에 대한 기준

문서화를 하는 기준에 대해서 아주 큰 범위로 나누어 보자면 다음과 같다.

  1. 나를 위해서 문서화를 하는 경우.
  2. 남을 위해서 문서화를 하는 경우.

이 기준에 따라서 개발자가 문서화를 하는 상황과 구체적인 사례를 알아보자.

나를 위한 문서화

나를 위해 문서화를 하는 경우에는 몇 가지 케이스가 존재한다.

  1. 내가 한 작업에 대해 상세하게 히스토리를 남겨 추후에도 활용하기 위해.
  2. 특정 정보들(자주쓰는 명령어, 어떠한 사용 방법 등의 간략한 정보들)을 정리하고 한 번에 보기 위해.

위의 케이스에 대해 구체적인 사례를 찾아보자.

  • 내가 이번에 Docker를 이용하여 이미지를 하나 만들었다. 베이스 이미지로 활용할 예정인데 어떠한 구성으로 되어있고, 어떻게 했는지 기록을 남겨 나중에 베이스 이미지를 업그레이드 하거나 다른 베이스를 만들어야 할 때 까먹지 않고 참고하게 문서로 남겨야겠다.
  • 특정 서비스에서 요구사항이 있어 해당 요구 사항이 반영된 기능을 하나 만들었다. 나중에 말로 설명하긴 빡세니까 문서에다 어떻게 생각해서 진행 했는지, 개발적인 부분은 어떻게 했는지 등을 기록해놓고 나중에 필요하면 공유 해야겠다.
  • 관리하는 서비스가 너무 많은데 각각 알아야 할 정보들이 다 다르고, 너무 많아. 한 곳에 정리해서 관리가 되었으면 좋겠어!

남을 위한 문서화

그에 반해 남을 위해 문서화 하는 경우는 다음이 있다.

  1. 개발 결과물에 대한 전체적인 그림을 정리하여 추후 남에게 전달하기 위해 사용하거나 공유를 위해.
  2. 내가 만든 서비스 혹은 특정 사용 툴에 대한 내부 가이드를 내려주기 위해.

위의 케이스에 대한 구체적인 사례를 들어보자.

  • 이번에 신규 서비스를 만들었는데, 아키텍처 구성이 괜찮게 나온것 같아. 이걸 정리해서 남들에게 공유하고 참고할 수 있도록 해야겠어.
  • 새로 도입한 툴이 있는데 사용 가이드를 만들어서 나도 나중에 보면서 사용하고 공유도 해서 남들도 사용하게 해야겠다.
  • 신규 입사자를 위해서 회사 생활이나 업무 등 기본적인 환경을 갖출 수 있게 참고 문서를 만들어야겠다.

이런 다양한 상황에서 문서화를 진행하게 되는데 보통 이런 문서화는 어느 정도의 퀄리티를 보장하려면 상당한 시간 투자가 필요하다. 보통 나를 위한 경우에는 나만 보기 때문에 내가 아는 방식으로만 작성해도 크게 문제가 되진 않지만 남이 보는 문서의 경우 대충 만들었다가는 사람들이 보려고 열었다가도 집중하기가 쉽지 않고 그렇게되면 문서는 잊혀지고 만다.

그럼 과연 어떻게 해야 문서화를 “잘” 할 수 있을까?

문서화를 잘 하려면?

여태까지 내가 문서화를 해오면서 느꼈던 방법을 말해보고자 한다.

공통적으로 필요한 것.

  • 목차를 짜임새 있게 지정 해야 한다.
    • 내가 문서화하는 주제에 대해 목차를 짜임새 있게 지정한다. 목차는 문서의 흐름을 파악하는데 가장 중요한 것이므로, 최대한 짜임새 있게 지정한다.
  • 요약을 일목요연하게 할 수 있어야 한다.
    • 문서화에는 자세하고 디테일한 내용을 “전부” 담을 수 없다. 최대한 요약해서 필수적인 정보를 최대한 제공해야 한다. 문서 성격에 따라 다르겠지만 대체로 핵심적인 내용만 적으려 해야 한다. 글과 내용이 쓸데없이 길어지게 되면, 피로감이 든다.
  • 시각적인 자료를 활용하고, 문서의 구조도 보기 좋게 다듬을 수 있어야 한다.
    • 단순히 텍스트를 양식 없이 늘어놓을 뿐 이라면, 그것은 문서가 아니라 정제되지 않은 글이다. 문서의 구조를 목차에 맞게 구성하여 보기 편하도록 해야 하며, 필요하다면 시각적 자료도 충분히 활용해야 읽는데 부담이 없다.
  • 보는 사람의 입장을 고려해야 한다.
    • 문서를 보는 사람의 입장에서 글을 작성해야 한다. 보는 사람이 내용을 이해할 수 있을지? 설명은 충분한지? 읽는데 불편하거나 모르는 부분이 생기진 않을지? 를 항상 고려해야 한다.

문서 유형에 따라 필요한 것.

  • 다른 사람에게 어떠한 것을 가이드 해주어야 하는 문서인 경우.
    • 보는 사람의 입장에서 최대한 자세하게 설명하되, 이해할 수 있는 깊이로 서술해야 한다.
      • 보통 이러한 경우에는 작성자는 작성하고자 하는 내용에 대해 “알고” 있는 상태이다. 따라서, 이런 상태에서 문서를 작성할 때 본인이 아는 내용에 대해 자세하게 기술하지 않거나 어떤 사실을 아는 것으로 가정하고 내용을 작성하는 경우가 많다. 이렇게 되면, 보는 사람은 이해하기 어려울 뿐 더러, 문서 자체를 보기가 힘들어진다.
      • 풍부한 예시와 이미지를 제공해서 설명할 수록 더 좋다. 글 보다는 직관적으로 이해하기 쉬운 이미지는 문서를 이해하는데 더 도움이 된다.
  • 나를 위한 기록/히스토리 성을 띄는 문서인 경우.
    • 다 까먹은 상태에서 보아도 이해할 수 있게끔 작성해야 한다.
      • 사람마다 다르지만, 잘 기억이 나지 않는 상태에서도 보면 이해할 수 있게 작성한다. 이해할 수 있게 작성하는 방법은 사람마다 다르다. 어떤 사람은 전체적으로 자세하게 다 적어야 할 수도 있고 어떤 사람은 키워드만 배치해 놓아도 기억이 날 수 있다. 이는 본인의 스타일 마다 다르지만 이미 안다고 특정 내용이나 부분을 스킵해서는 안된다.
    • 왜 이렇게 했는지 이유를 기록하거나 행동/결과에 대한 사유를 기록해야 한다.
      • 결과에 대한 요약을 정리하여도 그렇게 했었던 이유나 사유 등을 기록해놓지 않으면 추후에 문서를 다시 볼 때, 추적이 힘들다. 사유가 있어야 추후에 적절한 판단을 다시 내리거나 행동을 다시 해야 할 때 도움이 된다.

여기까지가 보통 내가 생각하는 문서화를 잘 하는데 필요한 방법들이다. 저런 것들을 전부 신경 쓰자면 상당한 시간이 소요되며, 처음부터 잘 할 수는 없다. 당장 나 조차도 저런 점들을 참고하여 꽤 괜찮은 문서를 작성하는 데에는 오랜 시간이 걸렸다.

그렇다면 어떻게 해야 저런 부분들을 잘 반영하여 문서를 작성할 수 있을까?

문서를 잘 작성하기 위해서는 무엇을 해야 할까?

  1. 일단 기록하고 정리하는 습관들 들인다.
    • 사소한 것을 작업하더라도 기록하고 정리하는 습관을 들여야 나중에 그보다 많은 내용의 문서를 작성하는데 도움이 된다.
    • 아주 작은 길이의 문서를 작성하다 보면 자연스레 큰 내용에 대해 작성하고자 할 때, 부담이 덜하다.
  2. 작성한 문서를 복기하고, 나중에 변경 사항이 생기면 업데이트를 한다.
    • 문서를 작성하고 나서도 항상 작성이 잘 되었는지, 남들이 보기에 문제가 없을지 복기한다.
    • 문서의 내용이 변경되거나 잘못된 점이 있다면 업데이트 하거나 수정을 해야 한다. 잘못된 정보가 계속 제공되는 문서는 신뢰도를 떨어트린다.
  3. 문서화 할 때, 본인만의 정리 플로우를 만든다.
    • 목차를 작성 후, 그에 맞게 내용을 채워나가는 방싱이나 내용을 채운 후, 목차를 뽑는 방식. 아니면 다른 어떠한 방식으로든 특정 주제에 대한 문서를 작성할 때 본인만의 플로우를 만들어 놓고 지속적으로 그에 맞게 문서를 작성한다.
    • 이런 플로우가 있을 때, 점점 문서화에 요구되는 시간이 줄어들 것이고 능숙하게 작성할 수 있다.
  4. 단순 문서화 프로그램이 아닌 툴이나 상용 서비스를 활용한다.
    • 문서화를 한다고 해서 꼭, 엑셀이나 파워포인트 등을 써야하는 것은 아니다. 공유 및 편집에 편리한 “구글 문서”, 뷰어가 편하고 깔끔하며, 가독성 좋은 “Notion”, 프로젝트/팀 단위의 문서 정리 아카이브 역할을 하는 “Confluence” 등 문서화에 도움을 주는 상용 툴이나 서비스를 적극 활용하는 것도 나쁘지 않다. 오히려 그런 프로그램에서는 문서화를 위한 많은 리소스나 에셋을 제공한다.

이런 점들을 신경 쓴다면 문서의 질이 높아지고 다른 사람들이 보기에도 편한 문서를 만들 수 있다. 100% 정확하고 무조건 적인 것은 아니지만 적어도 저런 요소들을 신경 써서 만든다면 실패하지는 않을 것이다.

문서화는 확실히 귀찮고, 시간이 많이 소요되는 작업이다. 하지만 확실하게 정리하고 기록해 놓으면 언젠가 도움이 되는 때가 오고 업무/협업의 효율성에 있어서도 큰 향상을 이루어 낼 수 있다.

또한, 특정 정보를 필요로하는 사람들에게는 사막 속 오아시스 처럼 큰 도움이 될 수 있을 것이다. 그러니 문서화에 대해 무작정 두려워 하거나 부정적으로 바라보지 말고 우리 모두를 위해 멋진 문서를 만들어 보자.

© 2024. Chiptune93 All rights reserved.