개발자의 글쓰기

호랑이는 죽어서 가죽을, 사업은 끝나고 문서가 남는다

Jan 11. 2025

10년 넘게 다양한 소프트웨어 개발 현장에서 일하다보니, 잘 알지 못하는 시스템을 분석하고 유지보수하는 일이 많았다. 자사 솔루션이나 서비스 기반의 비즈니스를 하는 회사에서 오래 일했다면 겪어보지 못했을 경험이다.

"독감 예측 데이터가 대시보드에 나오고 있지 않아요.

그리고 몇달째 예측 데이터가 업데이트 되고있지 않아요."

우리 회사에서 구축한 시스템은 아닌데, 고객의 요청으로 운영상의 문제를 해결하기 위한 인터뷰를 한적이 있다.

몇년전 구축사업에서 담당자였던 고객이고, 공기업이나 기관의 경우, 같은 조직에 있더라도 몇년에 한번씩 부서가 바뀌니 지금은 전혀 다른 업무를 하고 있었다. 고객이 담당한 시스템은 건강보험으로 보고되어 올라온 데이터를 취합해서 추출된 감염병 발생 데이터를 날씨 데이터와 융합해서 기상상황에 따라 감염병 발생 확률과 대비 방법을 알려주는 '감염병 기상예보' 같은 서비스였다.

사실 유지보수하고 있는 회사가 따로 있어 이치에 맞지 않지만, 고심끝에 우리 회사 대표에게 직접 연락해서 문제해결 방법을 같이 알아봐달라고 부탁한것이다. 새로 담당한 시스템의 운영을 하려고보니 잘 모르기도하고, 부서내의 이슈사항과 실제 시스템을 비교했을때 이상한 부분이 발견된것이다. 그런데 유지보수 업체에서는 요청을 해도 제대로 알려주거나 대응을 하지 않았다고 한다.

회사에서 문제해결을 위해 투입한 인원은 나를 포함해서 2명. 우리는 아무것도 모르는 시스템의 문제를 해결해야했는데, 운영중인 서비스는 존재하지만 시스템의 이해를 위해 참고할만한 문서 등의 자료는 제공되지 않았다. 담당자의 어렴풋한 경험과 동작중인 웹서비스, 유지보수용 개발환경만이 분석과 문제해결을 위해 주어진 재료였다. 심지어 시간을 들여 분석을 해봤을때 운영자 PC에 있는 자료와 유지보수 개발환경에 있는 자료의 시점이 다르고, 데이터베이스에는 비즈니스 도메인을 식별할만한 정보가 없었고, 소스코드의 주석이 중요한 비즈니스 로직을 설명하고 있지 않았다.

결국 서비스의 동작과 구조를 이해하는데 많은 시간을 들여야했고, 개발환경에서 테스트를 위해 실행해볼수도 없어서 운영중인 서버에서 구동할 모듈을 수정해서 배포해가며 문제를 식별하고 점차적으로 해결하는 방법밖에 없었다. 해당 시스템을 구축하지도, 유지보수를 위한 계약을 한 업체도 아니라 시스템 다운과 변경에 의해 뭔가 문제가 생긴다면 책임을 피하기 어려운 위험한 작업이었다.

나는 이런 작업은 할 수 없어 빠졌고, 같이 분석을 갔던 다른 개발자가 시간을 들여 작업을 시작했다.

며칠간의 시간이 들었지만 결국 제한적으로 고객이 요청한 소기의 목적을 달성할수는 있었다.

하지만 이런식으로 계속 운영할 수는 없기 때문에 해당 시스템은 얼마가지 못하고 폐기처리되었다.

유지보수가 필요한 소프트웨어는 바꿔 말하자면 사용할 가치가 있는 소프트웨어다. 그런데 유지보수가 필요한 대다수의 소프트웨어가 유지관리를 하는데 필요한 문서가 존재하지 않는다. 데이터베이스 테이블이나 필드에 어떤 역할을 하는지 라벨링이 되어있으면 다행인 지경이다. 코드에 주석을 작성하긴 하지만 모듈의 정체성과 목적에 대해 설명하고 있는 경우는 드물어 있으나 마나다. 그래서 대부분 남이 만들어놓은 소프트웨어를 분석하는 작업은 목적과 구성을 알지 못하는채로 맨땅에 헤딩하는 일이다.

가장 최악은 몇년전 구축한 DDoS 탐지를 위한 패킷분석 시스템을 분석하는 일이었다.

사업 기간은 종료시한을 넘어가고 있었고, 중요한 기능을 개발하기로 계약되어 있던 업체는 목표 기능을 충족하지 못하는 오픈소스를 개발서버에 설치하고 철수했을 뿐이었다.

아무것도 모르는채로 전임자가 철수하고난 상황과 해결방법을 분석해야했던 나는 프로젝트 진척상황, 설계 문서와 목표 시스템 구성등의 정보를 찾아봤지만 아무런 정보도 찾을 수 없었다. 그래서 개발서버에 설치된 패키지와 파일, 데이터베이스의 논리 구성, 프로젝트 요구사항을 하나씩 비교하며 문제점과 현상황을 파악해야했다. 가용한 자원과 목표를 비교했을때 이 상황 그대로 개선만 해서는 쓰러지기 직전인 젠가 탑을 스스로 무너뜨리는꼴 밖에 되지 않을것 같았다. 결국 나는 주요 소프트웨어를 전체 재개발하는 어려운 결정을 하고 그 책임을 졌다. 이렇게 시스템을 일목요연하게 알 수 있는 자료가 없으면 불필요한 비용이 들고, 최악의 경우 소프트웨어를 폐기해야할수도 있다.

사실 소프트웨어는 그 자체로는 큰 의미가 없다. 소프트웨어가 목표한대로 동작함으로서 고객에게 서비스를 제공해야 가치를 가지는것이다. 그리고 그 가치가 계속해서 유지 가능해야하며, 제어 가능함으로서 가치를 제공할 수 있는 기간을 늘려가는것이다. 단순히 소프트웨어를 보유하는것 보다 오래도록 사용되어야 의미가 있는것이다.

이것은 개발사 입장에서도 동일하다. 소프트웨어를 통해 매출을 창출해야하는데 유지보수를 할 수 없거나 재활용 할 수 없는 소프트웨어 및 기술은 가치를 높게 평가하기 어렵다.

소프트웨어 구축이후 시간이 지나, 담당자가 바뀌고 시스템을 이해하지 못한채로 유지보수를 하는 경우가 많다.

소프트웨어 품질관리를 위해 문서의 역할이 중요함에도 단순히 프로젝트의 절차로서 건성으로 작성하고 관리도 하지않기 때문이다. IT 아웃소싱을 통해 프로젝트를 마무리하면서 개발사에서 필수 문서를 작성해서 제출했음에도, 고객측에서 제대로 챙기지 않아 유실되는 경우를 예로 들 수 있다.

자사에서 개발한 프로젝트라 하더라도 고객사에 상주하여 프로젝트를 진행하는데 인터넷이 되지 않는 폐쇄망 환경에서 작업하는 경우가 많다보니, 별도로 작성한 문서를 반출하지 않았다면 시간이 지나 해당 시스템에 대해 기억하고 있는 사람이 없어 처음부터 분석을 해야하는 경우가 생기는것이다. 고객은 시스템을 개발한 개발사라서 믿고 유지보수를 맡겼지만, 소프트웨어 유지관리 품질은 처음 소프트웨어를 분석하는 다른 회사와 다르지 않게 되어버린다.

소프트웨어를 구성하는 코드가 과일의 알맹이라면 문서는 껍질이고, 합쳐서 소프트웨어의 정체성을 지닌다.

어느 하나라도 문제가 있다면 소프트웨어의 수명을 장담할 수 없게 된다. 소프트웨어가 수명을 다하는 순간은 사용자에게 더 이상 필요하지 않을때, 개발사에서 더 이상 매출을 창출 하지 못할때다. 어느 한쪽이라도 가치가 없어진다면 머지않아 이 소프트웨어는 세상에서 사라질것이다. 이러한 리스크를 최소화 하기 위해서는 소프트웨어를 실행가능한 프로그램으로만 볼게 아니라, 비즈니스 목표와 시스템의 구조, 논리를 이해하는 자료를 포괄하는 좀 더 넓은 의미에서 보고 관리해야한다.

개발을 위해 사용되었던 기술, 고객 사이트에서의 업무 이력, 노하우 등을 정리해서 회사의 자산으로서 관리하고 모든 구성원들이 보고 익힐 수 있도록 해야한다. 상주 프로젝트를 수행했다고 하더라도 조금 불편하겠지만 사업이 끝난 이후 별도로 시간을 내어 정보를 정리해야한다. 그러기 위해서는 업무내용을 기록하는 습관을 들여야하며, 주기적으로 정리해서 모아놓을 수 있는 환경과 문화가 이루어져야한다. 이러한 지적 재산이 모여서 잘하는 일을 더 잘하는 생산성 높은 조직이 될것이다.

개발자는 단순히 전문기술직(또는 생산직)으로 생각하기 쉽지만 사실 사무직에 가깝다.

개발자가 키보드를 두드리는 대부분의 시간은 코딩을 위해서 할애되기를 원하지만, 회사에서 근무하다보면 소프트웨어 설계문서 외에도 출장계획서, 업무보고서, 사업제안서, 연구계획서 및 결과서 등 다양한 업무용 문서와 증빙서류를 작성할 일이 많다. 회사의 사무직 구성원들이 이러한 업무를 하는 이유는 간단히 말하자면 경영상의 업무공백이 생기지 않도록 하기 위함이다. 마찬가지로 소프트웨어 품질관리를 위한 문서화도 개발자의 업무로서 정의하고 수용할줄 알아야 불필요한 업무공백이 발생하지 않을것이다.

소설이나 논평 등 독자에게 이야기나 정보를 전달하는 글과 다르게 개발자의 글은 사실을 담백하게 전달하는게 목표다. 소프트웨어 설계문서 외에도 릴리스 문서, 장애 보고서, 개발 가이드, 사용자 매뉴얼, 운영자 매뉴얼 등을 일반적으로 쓰게 될텐데 대부분 고객에게 전달하는 글을 쓴다는 인식이 낮은게 현실이다. 마치 개발자의 업무는 코딩의 영역을 벗어나면 안되는것처럼 스스로 제약을 거는것이다.

여러가지 원인이 있겠지만 기본적으로 사람과 대면을 하거나, 서면으로 무언가를 전달하는 등 커뮤니케이션에 거부감이 들고 두려움이 있는 내향적인 성격의 사람들이 개발자라는 직업을 많이 선택하기 때문이다. 코드를 쓰는것과 다르게 의사소통을 하는 대상이 컴퓨터가 아닌 생각을 하는 사람이라는데서 오는 불안과 막막함이 있는것 같다. 코로나19 팬데믹 시대를 지나오며 더욱 보편화된 전화공포증과 유사하다.

처음부터 글을 잘 쓰지 못하는것은 어찌보면 당연한 일이다.

학창시절 문과, 이과 이분법적인 분류로 나뉘어 공부를 해왔고 사지선다, 단답식 위주의 학습과 응답에 익숙해져 그 방식이 평생을 좌우하고 있는것이다. 하지만 익숙하지 않다고 피하기만해서는 발전은 있을 수 없다.

글을 잘 쓰는 방법은 긴말할 필요없이 많이 써보면 된다.

업무를 하거나 지식을 익히면서 틈틈히 기록하는것으로 글쓰기를 시작해보자. 독서노트를 쓰거나, 회의록을 쓰거나, 강의를 들으면서 메모하는 습관을 들이는것도 좋다. 이야기를 듣거나 읽은 글에서 중요하다고 생각되는 키워드와 키워드간의 관계를 간단히 기록해놓고, 긴 시간이 지나기전에 나름대로 키워드를 엮어서 의미있는 짧은 글을 작성하다보면 문장력도 점차 늘게될것이다.