저작권 안내: 저작권자표시 Yes 상업적이용 No 컨텐츠변경 No

스프링5 입문

JSP 2.3

JPA 입문

DDD Start

인프런 객체 지향 입문 강의

'문서'에 해당되는 글 1건

  1. 2016.08.03 문서

문서

개발자이야기 2016.08.03 21:47

난 개발과 관련해서 문서 작성을 선호하는 편이다. 그렇다고 검수 산출물과 같은 형식적인 문서 작성을 선호하는 것은 아니다. 주로 다음을 위한 문서 작성을 선호한다.

  • 대화 재료
  • 미래에 시스템을 운영할 사람

대화 재료로서의 문서는 회의에서 효과가 크다. 기능 스펙, 설계 초안, 구현 아이디어, 목차 등을 정리한 문서는 대화를 시작하기 위한 좋은 재료가 된다. 이때 문서는 소통이 가능한 수준의 내용만 담으면 된다. 간단한 클래스 다이어그램이나 상태 다이어그램이어도 되고, 자유 형식의 사용자 스토리여도 된다. 또는 종이에 끄적인 내용을 복사해서 함께 봐도 되고, 화이트보드에 그려 놓은 내용을 사진으로 찍어 출력한 문서여도 된다. 이 문서를 바탕으로 대화를 하면서 내용을 발전시켜 나갈 수만 있으면 된다.


대화 재료로 사용할 문서가 격식을 갖출 필요는 없지만, 그렇다고 내용을 대충 만들어도 된다는 건 아니다. 재료가 나쁘면 대화도 함께 나빠진다. 대화 과정에서 발전시켜야 할 내용이 문서에 없으면, 그 문서는 도움이 안 된다. 그래서, 대화 재료에 사용할 문서를 작성하는 사람은 논의할 내용의 핵심이 잘 담기도록 노력해야 한다.


잘 만든 문서 하나는 대화 참석자를 빠르게 핵심 주제로 안내하고 대화 결과물이 좋을 가능성을 높여준다. 몇 년 전에 스프링캠프 발표 주제를 정리하기 위해 운영진과 회의를 한 적이 있다. 그때 발표하고 싶은 주제와 개요 수준의 목차를 담은 마인드맵 문서를 대화 재료로 들고 나갔다. 그 문서를 기반으로 빠르게 컨텍스트를 맞춘 덕에 회의가 수월하게 끝난 기억이 난다.


미래에 시스템을 운영할 사람을 위한 문서는 중요하다. 퇴사 시점에 이런 문서를 작성해서 후임자에게 넘기는 경우가 많은데, 그 시점보다는 중요 마일스톤을 찍는 시점에 운영과 관련된 문서도 함께 정리하는 것이 좋은 것 같다. 한참 시간이 흘러 작성하려면 왜 배포 과정에서 우회 방법을 선택했는지, 특정 IP를 왜 열었는지와 같은 이유를 잊게 된다. 이는 중요한 정보를 사라지게 만든다.


운영을 위한 문서는 코드처럼 정리를 해야 한다. 더 이상 필요 없으면 삭제해서 혼란을 제거하고, 기존 문서의 설명과 다른 절차가 추가되었다면 반영해서 정보가 사라지지 않도록 해야 한다. 운영을 위한 문서가 현재를 반영하지 못하면 그 문서는 죽은 문서가 되고, 중요 정보를 구전으로 전수받아야할 상황이 발생한다.


이런 문서는 정확한 표현이 중요하다. 애매모호한 표현을 사용하면 문서를 읽는 사람을 혼란스럽게 할뿐이다. 이는 말로 하는 것과 차이가 없다. 말로 전달하는 것 이상의 효과를 얻으려면 공유할 내용을 적절한 방법으로 표현하는 연습을 해야 한다. 경우에 따라 문장을 쓰거나 코드를 보여주거나 다이어그램으로 표현할 수 있어야 한다. 


이런 표현력이 쌓이면 대화 중에도 즉석에서 도움이 되는 대화 재료를 만들 수 있다. 아래 그림은 몇 해 전에 회의 중간에 그린 다이어그램이다. 간단한 다이어그램이지만 이 그림이 나오기 전까지 회의에 참여한 사람들은 서로 다른 소리를 하고 있었다. 개발자, PM, 기획자, 또 다른 개발자가 같은 이야기를 듣고 서로 다르게 이해를 했다. 그런 상황이 계속될 기미가 보이기 시작해서, 자리에서 일어나 화이트보드에 대화를 정리하기 위한 다이어그램을 그렸다. 이 그림이 그려진 이후 같은 이해를 바탕으로 회의가 정리되기 시작했다.



개발자가 본능적으로 문서 작성을 싫어하는지는 모르겠지만, 좋은(?) 개발자가 되려면 의사소통 능력이 중요하며 그 능력을 향상시켜주는 것 중 하나가 문서 작성 역량이라고 생각한다. 문서는 말과 함께 의사소통을 위한 중요한 수단이기 때문이다. 코드의 표현력이 중요한 이유가 코드에 담긴 지식을 자신을 포함한 누군가에게 전달하기 위함인것처럼, 동일하게 문서 역시 누군가에게 뭔가를 전달할 때 사용할 수 있는 방법이다.


문서를 작성하는 것은 너무 너무 귀찮은 일이지만, 도움이 되는 문서를 제대로 작성하는 것은  매우 중요한 일이기도 하다. 이 중요한 일을 잘 하기 위한 연습을 게을리하는 개발자는 되지 말자.


Posted by 최범균 madvirus

댓글을 달아 주세요