소프트웨어 문서 작성

Published by Woong Geun Jang, February 26th, 2018

소프트웨어 문서는 과유불급이다.

문서는 필수지만,

문서도 프로덕트와 마찬가지로 생명이 있기 때문에,

한 번 출판한 문서는 업데이트를 꾸준히 하는 것이 필수고,

시간이 지나면 가치가 떨어지는 정보를 업데이트하지 않으면

문서는 있으나 마나다.

그만큼 시간과 노력이 많이 필요하다는 것이다.

특히 컨센서스가 맺어지지 않은 사항에 대해서 문서화 하면

업데이트에 드는 비용이 엄청 크기 때문에

가능하면 뭔가 의견을 맞추는 문제에 대해서는 문서화를 최대한 미루는 것이 답이다.

문서를 쓰고자 결정했을 때,

어떻게 써야 하는가?

소프트웨어 문서 작성에서의 우선순위는 다음과 같다.

컨텐츠를 잘 쓰는 것이 필수고, 잘 꾸며지고 포맷이 이쁘다고 한 들, 유저가 어떤 정보도 얻어갈 수 없으면 무용지물. 당연하고 늘 강조해야 하지만, 일과 보이는 성과에 집중하다 보면 놓치고 갈 수 있는 부분.

소프트웨어 개발에서 자동화는 업무자가 문서 컨텐츠의 퀄리티에 좀 더 치중할 수 있게 도와주는 시스템이다. 개발자가 코드 퀄리티에 집중할 수 있도록 CI를 만들듯이 문서 또한 동일하게 적용하는 것.

포맷을 고려할 때도 여러가지 우선순위로 나눌 수 있다. 데코레이션. 회사의 아이덴티티를 반영한 테마 등이 있겠지만, 역시 가장 중요한 것은 유저가 정보를 얻기 위해 '편한 포맷인가’하는 것. 정보를 쉽게 찾을 수 있는가? 가독성이 좋은가? 등을 보아야 한다.