코드보다 더 어려운 문서작성, 이것만은 지켜보자.

좋은 문서가 필요한 이유

IT 조직에서, 잘 작성된 개발 문서는 중요하다.

잘 정리된 문서가 있으면, 같은 질문이 올라오는 시간도 줄일 수 있고, 같은 답변을 하는 시간도 줄일 수 있다.

문서화는 한번 해두는게 귀찮지만, 한번 해두면 시간이 지날수록 위력을 발휘한다.

좋은 문서를 작성하기 위한 최소한의 원칙

0. 우선 시작하자.

개발 문서 작성이 중요하다는 것은 많은 개발자들이 인식하고 있겠지만, 글을 막상 쓴다는 것은 막막하게 느껴진다.

• 우선 작성하는 것 먼저 시작하자. 무겁지 않고 가벼운 글이라도 좋다.
• 잘 작성된 1개의 글보다, 가볍게 작성된 10개의 글이 조직에 더 큰 도움이 될 수 있다.

1. 읽기 쉬운 문서

문서는 쓰는 사람보다 읽는 사람이 훨씬 더 많다. 읽는 사람이 쉽게 이해할 수 있어야, 문서의 가치가 더 빛을 발한다. 아래의 노력들을 통해, 읽기 쉬운 문서를 작성해보자.

• 독자가 이해하기 어려운 용어는 지양하고, 최대한 쉬운 용어를 사용하자. 불가피하게 어려운 용어를 써야 한다면, 단어에 대한 설명을 적거나 링크를 달아두자.
• 독자가 문서의 구조를 이해할 수 있도록, 문서 상단에 목차를 달아보자.
• 문서 작성의 이유를 문서 초반에 적어두는 것도 좋다. 이 문서가 왜 필요한지, 왜 이 문서를 작성했는지, 누구를 위해 이 문서를 작성했는지 서두에 적어둔다면, 독자의 이해도를 높일 수 있다.
• 문장은 간결하게 적어보자. 복잡하고 긴 문장, 여러 수식어들이 들어간 문장은 지양하자. 짧은 리듬으로 간결하게 작성된 문장으로 문서를 구성해보자.

2. 오해하지 않는 문서

다르게 이해할 여지가 있는 문장으로 쓰인 문서는 좋지 않다.

• 작성자의 의도 그대로 독자가 이해할 수 있는, 오해의 여지가 없는 글을 명확히 적어보자.
• 여러 의미를 함축하는 단어는 지양하자.
• 배경지식이 필요한 문서는, 관련 지식을 적어두거나, 혹은 이를 접할 수 있는 링크를 문서 초반에 달아두자.

3. 수정하기 쉬운 문서

처음에는 문서를 잘 작성해두더라도, 시간이 지나면서 문서는 낡기 마련이다. 업무환경이나 도메인 지식이 변경되는데, 문서를 지속적으로 갱신하지 않는다면, outdated된 문서가 될 수 밖에 없다.

• 혼자서 문서를 완벽하게 지속적으로 갱신할 수 없다면, 문서를 수정하기 쉽도록 만들어야 한다.
• 문서 수정이 쉬운 플랫폼에 문서를 작성하는 것도 좋다. 문서 수정이 쉬운 조직 문화도 필요하다.