본문 바로가기

문서

문서가 없으면 작은 프로젝트인 경우 문서를 거의 만들지 않고 개발을 하면 더 효율적이라고 생각할 수도 있다. 가끔은 그렇게 생각할 수도 있다. 너무 시간이 없다는 핑계를 대기도 한다. 하지만 이렇게 해서 모든 프로젝트에 문서가 거의 없으면 개선을 하려고 하는 회사에서 도움을 요청해도 막상 도와주기가 매우 어렵다. 문서가 거의 없어서 모든 것을 물어보면서 파악을 해야 한다. 있는 것이라고는 거의 쓸모 없는 문서와 소스코드인데 소스코드는 회사와 제품을 파악하는데 별 도움이 안된다. 문서가 제대로 있다면 80%는 문서를 보고 20%만 물어 보면 된다. 이때 개발을 하고 나서 나중에 만드는 문서는 그 효율성이 반으로 줄어든다. 나중에 만드므로 일단 충실도가 떨어지고 개발하기 전에 만들때 고려해야 할 요소들은 프로젝트가 이미 .. 더보기
문서화 딜레마 우리나라 소프트웨어 회사 중에서 문서를 제대로 작성하고 있는 곳을 찾기란 그리 쉬운 일이 아닙니다. 제대로 작성한다는 의미는 꼭 필요한 만큼 적절히 효과적으로 작성하는 것입니다. 대부분의 소프트웨어 회사는 변변한 문서 하나 없이 개발을 하고 있고 반대로 소수의 회사는 불필요한 문서를 잔뜩 만들어서 오히려 효율성을 떨어뜨리고 있습니다. 물론 제대로 하고 있는 회사도 있지만 그 수는 극히 적습니다. 대부분의 여러분들도 겪은 현상이거나 앞으로 겪을 것입니다. 변변한 문서하나 제대로 만들지 않고 소프트웨어를 개발하고 있는 회사는 구멍가게 이상의 규모로 성장하기 어렵습니다. 회사의 규모가 커지면서 문서가 부족하면 커뮤니케이션 비용이 기하급수로 증가하기 시작합니다. 회사가 작았을 때 숨어있던 문제들이 마구 터져 나.. 더보기
개발문서를 만들기는 했는데 업데이트가 안되는 이유 필자는 여러 소프트웨어 회사들의 컨설팅을 진행하면서 먼저 회사의 분석을 위해서 그 동안 소프트웨어를 개발하면서 만들어 놓은 문서를 요구합니다. 사실 문서만 봐도 회사의 개발현황을 대부분 알 수 있습니다. 그런데, 제대로 작성된 문서를 제시하는 회사는 거의 없다시피 합니다. 물론 Wiki나 Google Docs등의 온라인 문서를 포함해서 제대로 작성된 문서는 거의 없습니다. 가끔 문서를 제시하는 회사들이 있기는 하나 수년간 전혀 업데이트를 하지 않아서 쓸모가 없어진 것들 뿐입니다. 정리를 해보면 다음과 같습니다. 문서가 아예 없거나 없다시피 한 회사 몇 년동안 업데이트 안된 문서들만 있는 회사 (오늘의 주제) 쓸모없는 문서들을 너무 많이 만든 회사 야심차게 문서 한번 잘 만들어보겠다고 결심하고 개발 시에 .. 더보기
도대체 얼마나 자세히 적어 달라고?! 소프트웨어 개발자들에게 문서 작성은 고역이 아닐 수 없습니다. 그래서 문서는 소프트웨어를 개발한 후에 후배들에게 소프트웨어에의 스펙과 구조를 설명하기 위해서 작성하곤 합니다. 이런 경우에는 문서의 효용성도 별로 없을 뿐더러 문서가 제대로 작성되었는지 알기도 어렵습니다. 또 개발자들은 기억을 더듬어서 문서를 작성하기도 어려울 뿐더러 이러한 작업은 하기 싫은 고역이 될 수 밖에 없습니다. 소프트웨어를 개발하는데 있어서 필수적인 문서의 대부분은 개발한 내용을 정리하기 위해서 만드는 것이 아니고, 소프트웨어를 개발하는데 필요한 내용을 앞 단계에서 작성하는 것입니다. 즉, 설계를 하기 전에 스펙을 작성하고 구현을 하기 전에 설계서를 작성하고 테스트를 하기 전에 테스트 계획 및 TCL(Test Case List)를.. 더보기
악순환 vs. 선순환 지난번 글 (이 바닥을 못 벗어 난다.)의 추가 글입니다. 회사가 Risk가 큼에도 불구하고 Domain 지식이 점점 더 매달릴 수 밖에 없는 이유와 선순환을 하려면 어떻게 해야 하는지 좀더 현실감 있는 예를 보여주려고 합니다. 회사마다 상황이 모두 다르기 때문에 각자의 상황과 1:1로 다 일치하지는 않지만 참고하실 수는 있을 겁니다. 그럼 악순환과 선순환에 대해서 알아보죠. Domain 지식에 점점 매달리게 되는 악순환의 고리 주먹구구식 개발 개발자에 의존한 코딩 중심의 개발 주도 없거나 빈약한 개발 프로세스 및 개발 문서 회사의 지식은 개발자 머리 속에 보관 개발자 간 지식의 공유가 어려움 후배 개발자들에게 지식 전달이 잘 안됨 프로젝트가 커질수록 협업이 점점 어려워짐 점점 더 경험 많은 개발자에 의.. 더보기
개발자 여러분~ 문서 만들기 싫죠? 흔히들 소프트웨어를 개발하는데 문서를 만드느라고 시간이 더 오래 걸린다고 생각합니다. 문서가 필요한 것은 알고 있는데, 만들기는 싫다고들 합니다. 이러한 생각을 깨기 전에는 문서의 필요성에 대해서 이해하기가 어렵습니다. 소프트웨어를 개발하는데 문서를 만들어서 더 오래 걸렸다면 잘못된 것입니다. 필요도 없는 문서를 잔뜩 만들고 있거나, 문서를 작성하는 실력이 없어서 낑낑대고 시간만 잡아먹는 경우 일겁니다. 두번째 경우야 그러면서 실력이 늘 수도 있지만, 필요 없는 문서를 잔뜩 만들고 있다면 정말 헛고생하고 있는 겁니다. 문서를 만드는 이유는 소프트웨어를 더 빨리 만들기 위해서 입니다. 거꾸로 문서도 안 만들고 어떻게 더 빨리 만들 수 있냐고 반문하고 싶습니다. 모든 내용을 머리 속으로 모두 기억하고 있다?.. 더보기
Track me, if you can "요구사항 추적"이라는 말을 들어 보셨을 겁니다. 요구사항, 기능, 컴포넌트(클래스), 파일, 함수들의 연관관계를 추적하여 특정 요구사항에 관련된 컴포넌트나 소스코드들을 추적하고, 거꾸로 함수가 바뀔 때 이 변경에 영향을 받는 요구사항을 알아낼 수 있습니다. 왠지 근사해 보입니다. 실제로 요구사항을 추적하려고 노력하는 회사를 종종 보게 됩니다. 하지만 요구사항을 추적할 필요도 없는 작은 소프트웨어이거나 엉터리로 하고 있는 경우가 대부분입니다. 아니 100%입니다. 요구사항 추적이라는 것이 말만 근사해 보이지, 대부분의 역량으로는 거의 불가능합니다. 또 요구사항 추적툴 없이 엑셀파일에 끄적거려서는 할 수 없는 일입니다. 요구사항 추적은 사람의 생명을 다루는 소프트웨어이거나 엄청난 비용과 테스트가 불가능한 .. 더보기
커뮤니케이션 오류 소프트웨어 프로젝트를 진행하다 보면 수많은 커뮤니케이션의 오류를 발견하게 됩니다. 문서화 되지 않은 수많은 의견과 결정들에 대한 오해와 대화를 하면서 발생하는 표현의 오류는 한 두개가 아닙니다. 이는 비단 프로젝트에서 뿐만 아니라 일상생활에서도 벌어지는 현상이지만, 일상생활에서의 커뮤니케이션 오류는 그렇게 심각하지 않을 수 있지만, 프로젝트에서의 커뮤니케이션 오류는 심각한 손실을 초래하기 때문에 조심할 필요가 있습니다. 따라서 프로젝트를 진행하면서 오가는 대화나 기록은 명확해야 합니다. 미사여구보다는 직설적인 화법으로 핵심을 정확하게 말해야 합니다. 또 하나의 문장은 사실, 의견, 추축, 가정, 결정 또는 정보일 수 있습니다. 그런데, 현재 하고 있는 말이 사실인지 의견이지 명확하게 하지 않으면 수많은 .. 더보기
소프트웨어 개발의 극과 극 꽤 오래 전에 TV에서 "비교체험 극과 극"이라는 프로그램을 방영한 적이 있습니다. 어떤 아이템을 정해서 가장 비싼 것과 가장 싼 것을 비교하는 프로그램이었는데 꽤 재미있게 본 기억이 납니다. 소프트웨어를 개발하는 현장에서도 극과 극 현상은 드물지 않게 발생합니다. 여러 회사를 분석해보면 완전 주먹구구이거나 또는 너무 무거운 방법론을 도입해서 오히려 부담이 되는 경우가 많습니다. 적당히 중간인 회사를 찾기가 더 어렵습니다. 완전 주먹구구식 가내수공업 형태의 개발방식도 문제가 있지만, 몸집과 역량에 걸맞지 않은 거대한 방법론을 무조건 따라하는 것은 더 문제가 큽니다. 그럴 바에는 차라리 주먹구구가 낫습니다. 그런 주먹구구회사가 문제를 깨닫고 거대 방법론들을 스스로 연구해서 도입을 하면 그 핵심은 모르고 형.. 더보기
개발자도 문서를 잘 작성할 수 있어야 한다. 개발자(엔지니어)들이 문서를 잘 작성하지 못한다는 것은 익히 알려져 있는 사실입니다. 개발자에게 프로그래밍 실력이 더 중요하지 문서 작성 기술이 얼마나 중요하겠냐?라고 생각하는 사람이 있을 수도 있겠지만, 개발자가 성장할수록 문서 작성 능력의 중요도는 점점 더 커집니다. 문서를 잘 작성하지 못하는 개발자는 협업을 하는데 있어서 치명적인 결함을 가지고 있다고 할 수 있습니다. 그럼 문서를 잘 작성하는 것은 무엇이고? 문서를 잘 작성하지 못하는 것은 무엇일까요? 잘 작성되지 못한 문서의 특징을 한번 살펴보죠. 문서의 내용이 쉽게 이해가 되지 않는다. 외계어로 작성된 것 같다. 여백 없이 빽빽이 작성되어서 읽는데 너무 피곤하다. 문법이 많이 틀려서 내용도 신뢰가 가지 않는다. 주어도 없고 문장의 앞뒤가 전혀 .. 더보기