개발자의 글쓰기

책을 읽게 된 계기

 개발자, 연구원, 의료기기 R&D를 업으로 하는 사람들이 있다. 이 사람들은 소스코드를 만들거나, 연구 노트를 작성하거나 의료기기 R&D의 경우 의료기기 인허가와 관련한 기술문서를 작성한다. 또 자기 계발을 하는 사람들은 관련 기술 블로그 등으로 여러 지식을 정리하기도 한다. 회사에서 일을 하면서 여러 문서 작업을 했다. 이 작업 중 어떻게 하면 의사소통에 문제없이 문서들과 자료를 만들 수 있을지 많이 고민하였다. 또 블로그에 글을 작성하면서 어떻게 글을 읽는 독자들이 쉽게 읽어나갈 수 있을지 고민하였다. 이러한 고민들을 하던 중 이번에 서평을 작성할 책을 찾게 되었다. 앞의 고민들이 있는 상황에서 정말 매력적인 제목을 가진 책이었다. 이 책의 제목은 ‘개발자의 글쓰기’이다. 제목 옆의 부제는 ‘변수 네이밍부터 릴리즈 노트, 장애 보고서, 기술 블로그까지, 프로그래머의 글쓰기 고민 끝!’이다. 연구 부분과 의료기기 인허가 부분에 대한 글쓰기는 내용에 없지만 개발자의 글쓰기에 있는 내용을 이에 응용해 볼 수 있을 것 같았다.

개발자의 글쓰기 책 표지. 아이콘을 바탕으로 개발자와 글쓰기라는 주제를 잘 표현했다.

 

의료기기 R&D를 하는 사람의 글쓰기

 나는 일을 하면서 개발자와 연구자 그리고 의료기기 인허가라는 3가지 부분에 대한 글을 작성한다. 개발자로서는 소스코드를 만들고, 소프트웨어 패키지 배포 시 릴리즈 노트를 작성한다. 또 간단한 개발 가이드 문서를 작성한 적이 있다. 이와 더불어 버그 발생 보고서 등을 작성하기도 했다. 연구자로서는 기획한 기능의 성능에 대한 연구를 진행하며 실험 프로토콜 계획서, 실험 보고서 등을 작성하였다. 의료기기 인허가 부분에서는 각종 기술문서와 설계 문서 등을 조금 작성해보았다.

 지금 책에 대한 글을 쓰는 것과 같이 나의 생각과 경험을 정리하며 블로그에 글을 쓰기도 한다. 이러한 글들은 연구 및 개발을 하면서 내가 한 것을 정리하며 글을 쓰거나, 책에서 의미 있는 내용을 글을 쓰기도 한다. 또 관련 지식에 대한 정보를 정리하여 글로 남기기도 한다.

 내가 현재 다양하게 작성하고 있는 글들이 어떤 것인지 스스로 정리해보았다. 이러한 글들에 대한 방법을 정리하고 경험을 공유(?)하고자 한다. 이와 더불어 내가 하는 글쓰기들에 필요한 부분을 책에서 찾아보며 같이 정리해보았다.

 

개발자로서 글쓰기

 개발자로서 작성하는 글들에는 기본적으로 소프트웨어 개발을 위한 코드 및 주석의 작성, 소프트웨어에서 발생하는 에러의 문구에 대한 작성, 소프트웨어를 배포하며 작성하는 릴리즈 노트, 사용자로부터 이슈를 받아 작성하는 장애 보고서, 마지막으로 다른 개발자와 함께 협업하기 위한 개발 가이드 문서가 있다. 내가 이러한 글을 작성한 경험과 각각의 항목별로 책에서 배울 수 있던 부분을 정리해보았다.

코드 및 주석

 소프트웨어의 소스 코드는 여러 사람이 함께 작업을 해야 한다. 이러한 소스코드는 어떤 개발자가 보아도 쉽게 이해할 수 있으면 좋다. 즉, 원하는 목표를 소프트웨어로 구현하는 또 동시에 의사소통을 고려한 소스코드 작성이 필요하다. 의사소통을 위한 소스코드의 작성의 첫 번째는 여러 변수와 함수의 네이밍이다. 이 책에서는 이러한 네이밍에 대하여 'SMART'라는 방법을 추천한다. 'SMART'는 각각의 요소를 하나씩 합쳐놓은 약자이다. 각각의 요소는 아래와 같다.

1. 검색하기 쉽게 이름 짓기 (easy to Search)  
2. 조합하기 쉽게 이름 짓기 (easy to Mix)  
3. 수긍하기 쉽게 이름 짓기 (easy to Agree)  
4. 기억하기 쉽게 이름 짓기 (easy to Remember)  
5. 입력하기 쉽게 이름 짓기 (easy to Type)  

 코드를 작성할 때 추가적인 설명이 꼭 필요한 경우 주석을 작성한다. 이 주석 또한 개발에 참여하는 다른 개발자 사이의 소통을 돕기 위한 요소이다. 기본적으로는 주석이 필요하지 않도록 코드를 작성하는 것이 좋다. 하지만 코드로 어떤 수학, 물리적인 요소를 표현하는 경우 설명이 필요하므로 주석이 필요하다. 또 여러 방법 중 어떠한 의도를 가지고 방법이 선택되었는지 나타낼 때도 주석이 필요하다.

에러

 소프트웨어를 사용자가 사용할 때, 문제가 생기는 경우 사용자에게 표기되는 아무런 메시지가 없다면 사용성이 떨어지는 소프트웨어이다. 개발자는 사용성을 위해 기본적으로 여러 문제 사항에 대하여 어떤 문제가 발생하였고 어떤 조치를 취할 수 있는지 에러로 표기한다. 이러한 에러 메시지는 사용자와 개발자 사이의 의사소통방법이다. 에러가 발생하는 원인은 크게 두 가지로 볼 수 있다. 하나는 개발자가 버그가 있는 코드를 작성하여 문제가 발생한 경우이다. 이 경우 버그를 잘 수정해야 한다. 다른 하나는 사용자가 의도된 사용을 하지 않아 문제가 생긴 경우이다. 이 경우 문제의 내용을 알려주고 어떠한 원인으로 문제가 발생하였는지 알리고 마지막으로 해결 방법을 제시해야 한다. 이러한 에러 메시지에 신경을 많이 쓰지 않는 이유는 시간이 없거나 사용자가 의도된 사용을 지킬 것이라는 근거 없는 믿음으로 인한 것이라고 생각한다.

 사용자가 지속적으로 의도된 사용을 하지 않으면 어떻게 해야 할까? 현재 에러 메시지에 문제 내용, 원인, 해결 방법만 담으면 될까? 이럴 때는 소프트웨어에 그 기능이 사용성이 떨어지도록 잘못 설계된 것이다. 이때는 사용자의 실수(의도하지 않은 사용)를 사전에 차단해야 한다. 예를 들면 예약 시스템의 경우 오늘 이전의 날짜는 선택할 수 없도록 막아버리는 것이다. 예약은 미래에 있는 일인데 사용자가 과거의 날짜를 실수로 눌러 에러 메시지를 보는 것은 적절하지 않다. 사용성을 고려하여 과거의 날짜를 누르지 않도록 사전에 실수하지 않도록 사전에 방지해야 한다. 이렇게 사용자의 실수를 무조건 막는 방법은 또 다른 사용성의 불편함을 가져올 수 있다. 따라서 좋은 소프트웨어의 사용성을 위해 에러 메시지와 사용자의 실수를 차단하는 방법을 개발자는 적절하게 구현해야 한다.

릴리즈 노트

 릴리즈 노트의 핵심은 어떤 사람이 이 릴리즈 노트를 확인하는가이다. 팀 내에서 릴리즈 노트를 확인한다면 정말 세세한 것까지 잘 적어야 한다. 하지만 외부에 있는, 제품을 사용하는 사용자에게 릴리즈 노트를 보내야 하는 경우 그 사용자에게 필요한 부분만 릴리즈 노트로 작성해야 한다. 여기서 이 릴리즈 노트를 잘 이해하도록 적는 것은 당연한 일이다. 즉, 구분하여 릴리즈 노트를 관리할 필요가 있다. 나는 이러한 모든 릴리즈 노트를 git으로 관리한다. 여기서 팀 내 배포 시 이 릴리즈 노트의 세세한 부분을 작성하여 공유한다. 또 소프트웨어 배포를 할 때에는 고객에게(일반적으로 사내의 고객 서비스 팀에게 보낸다) 필요한 부분을 골라낸다. 이후 소프트웨어 사용 절차에 맞게 카테고리로 정리한다. 마지막으로 이 고객이 쉽게 이해할 수 있게 풀어서 설명을 작성한다. 최근에는 글과 더불어 변경된 부분을 그림과 도식으로 설명을 붙여 넣기도 한다.

팀 내 및 고객에 따른 릴리즈 사항 차이 도식.

 사실 릴리즈 노트는 보편적인 소프트웨어 회사와 다르게 의료기기의 시스템에 대한 릴리즈 노트를 작성하여 내용면에서 차이가 있었다. 이 책에서 참고할 만한 점은 다른 소프트웨어들이 어떻게 릴리즈 노트가 작성되고 있는지 확인해보는 부분이다. 세계적으로 유명한 여러 회사의 순수한 소프트웨어 릴리즈 노트, 하드웨어와 함께 릴리즈 되는 제품의 릴리즈 노트를 참고하면 다음에 내가 릴리즈 노트를 작성할 때 도움이 될 것 같았다.

장애 보고서

 나는 업무 중 장애 보고서를 작성한 적은 없다. 다만 이슈라는 이름으로 내용을 접수하고 상황과 문제의 원인을 정리한 적은 많다. 이러한 이슈 접수 및 보고에 대한 부분을 절차로 설명해보겠다. 먼저 앞에서 언급한 것과 같이 상황과 문제의 원인을 먼저 정리한다. 이후 문제의 원인을 해결할 해결 방안과 일정을 산출하여 팀 내에 보고한다. 이 책에서 참고할 만 점은 일정을 산출하는 것에서 멈추지 말고 이 이슈가 마무리되는 동안의 비즈니스적인 부분도 작성하여 팀과 공유할 수 있으며 좋다는 부분이다.

개발 가이드 문서

 지금은 내가 하는 일이 너무 바빠 다른 사람을 위한 개발 가이드 문서를 작성하지 않는다. 틈틈이 작성할 수 있도록 해야겠다는 생각이 들었다. 나는 개발하면서 소스코드에 대하여 리팩터링을 해야 한다는 생각을 가지고 있다. 리팩터링을 하면서 현재 스파게티처럼 꼬여있는 코드들을 풀고 덜어내는 작업을 진행할 것 같다. 소스 코드를 덜어내면 모듈화가 진행되는데 이러한 모듈에 대한 사용법, 개발 가이드 문서를 같이 작성할 수 있다면 좋겠다는 생각을 했다. 지금 내가 해볼 수 있는 것 무엇일까? 나는 기능 개발에 있어 어떻게 이 기능을 구현할 수 있을지 작성하고는 한다. 어떠한 계산과 수식을 거쳐 기능에 필요한 연산이 완료되는지 수식 및 도식으로 정리한다. 이때 소스 코드에 대한 부분을 작성하지 않는다. 개발 가이드의 경험과 다른 개발자와의 소통을 위해 어떠한 소스 코드를 테스트로 하여 확인하였는지, 생각과 근거를 소스코드와 함께 정리해두면 좋을 것 같다. 이러한 정리가 모여 작은 개발 가이드 문서가 될 수 있을 것이다.

 

연구자로서 글쓰기

 내가 연구자로서 작성하는 글들에는 어떤 것이 있는지 다시 확인해보자. 기능에 대한 가능성을 확인하기 위한 연구 및 실험을 자주 한다. 이러한 기능과 사용 가능성에 대한 제안서를 작성한다. 또 제안서에 가능성을 확인하기 위한 실험을 진행하므로 이에 대한 실험 프로토콜과 실험 보고서를 작성한다. 위의 문서를 작성할 때의 나의 경험과 책에서 참고할만한 내용을 정리해보았다. 책에서는 연구자로서 글쓰기와 잘 맞는 단원은 없었지만 주로 '6장 수주를 돕는 SI 제안서 쓰기'에서 참고할만한 내용이 많이 있었다.

기능 기획 및 이 기능의 사용 가능성에 대한 제안서

 의료기기에 추가되거나 변경되는 기능들은 사용성과 성능 그리고 안전성이라는 세 가지 측면에서 많은 연구를 거쳐 만들어지게 된다. 여러 요소를 고려하여 기능에 대한 기획과 이에 대한 제안서를 작성해야 한다. 이렇게 작성된 제안서를 제품에 대한 방향을 결정할 수 있는 팀장 및 경영진, 그리고 제품을 사용하고 판매하는 영업과 고객 서비스 팀 더 나아가서 의료진까지 이해시키고 설득시켜야 한다. 보통의 개발과 다르게 다양한 요소가 고려되며 다양한 사람들의 요구 사항을 만족해야 한다.

 이 제안서를 작성하는 순서를 하나하나 정리해보자. 먼저 요구사항을 정확하게 확인하기 위해 이 요구사항이 어떻게 생겨나게 되었는지 상황을 정리한다. 타사 제품을 보았을 수도 있고, 사용자가 의견을 제시하였을 수도 있으며, 사용 중 문제가 발생하여 이에 대한 해결책을 떠올려 이야기한 것일 수 있다. 이러한 상황을 바탕으로 정확한 문제를 파악하여 이를 핵심 요구사항 혹은 문제, 원인으로 선정한다. 이후 이 요구사항을 해결하기 위한 기능을 제안한다. 이때 이 기능이 가지는 기존과 다른 부분, 장단점, 사용성과 성능 그리고 안전성에 대해 작성한다. 여기서 실험이 필요한 부분이 있는데 이는 실험이 필요한 것으로 표기해둔다. 기능에 대한 제안이므로 사용성 및 성능 그리고 안전성을 위해 연구 및 실험이 필요할 수 있기 때문이다. 이후 간단한 일정을 산출하여 정리한 후 제안서를 바탕으로 설득하거나 피드백을 받아 수정한다.

기능 기획에 대한 도식.

 이 책에서의 제안요청서 분석이 요구사항에 대한 정확한 확인과 일치하는 것 같다. 또 논리적 완결성 부분은 어떤 상황으로부터 요구사항을 추론했는지, 또 이 문제를 해결하기 위한 기능을 어떻게 추론했는지 잘 설명하는 것과 비슷하다. 상황, 요구사항 확인, 해결을 위한 기능 제안이라는 순차적인 흐름에 논리적으로 잘 설명이 되어야 한다. 또 몇몇 부분에 논리적 완결성을 더하기 위해 연구 및 실험을 따로 진행한다.

실험 프로토콜 및 실험 보고서

 위에서 작성된 제안서에 논리적 완결성을 연구 및 실험을 통해 더하게 된다. 이렇게 갖추어진 기능 기획 및 제안서는 많은 요소를 고려하였으므로 사람들을 설득할 가능성이 높다. 실험 프로토콜 및 실험 보고서는 순차적으로 진행하며, 프로토콜 작성 후 보고서를 작성한다.

 실험 프로토콜을 어떻게 작성하는지 순차적으로 확인해보자. 먼저 앞에서 설명한 기능에 대하여 간단하게 설명할 수 있는 개요 부분을 먼저 작성한다. 이후 이 개요에서 어떤 부분이 부족하므로 실험이 필요하다는 실험에 대한 목적을 분명히 한다. 실험의 목적이 정해졌다면 어떻게 실험을 수행하여 목적한 바를 확인할지 방법을 작성한다. 이 방법 작성에는 여러 도식과 수식 그리고 그림을 잘 활용하여 실험에 대한 오해가 없도록 하는 것이 중요하다. 이후 이러한 실험 프로토콜을 관련 연구자와 협의하여 피드백을 받아 수정하고 실험을 수행한다.

 실험 프로토콜을 바탕으로 실험이 진행되었다면 실험 보고서를 작성한다. 실험을 수행하고 결과를 정리한다. 그리고 이 결과로부터 얻어진 생각 및 의견을 정리한다. 이후 실험 프로토콜과 실험 보고서를 합하여 하나의 자료로 만든다. 이렇게 만들어진 자료에서 실험 결과와 의견이 실험 목적에 부합하고 논리적으로 맞는지 확인한다. 이후 이렇게 만들어진 논리가 기능 제안서에 부합하는지를 확인한다.

 기능 제안서와 연구 및 실험을 거쳐 만들어진 실험 프로토콜 및 실험 보고서가 논리적으로 완결성을 가진다면 이를 바탕으로 기능 구현을 수행한다.

 앞에서 설명한 논리로는 완결한 기능이 만들어질 것만 같다. 하지만 요구사항을 잘못 판단하였을 수도 있으며 여러 상황에 따라 요구 사항이 변경될 수도 있다. 이러한 변경에 대하여 유연하게 대처할 수 있도록 자료를 준비하고 소스 코드를 수정할 수 있게 잘 작성하는 것이 정말 중요하다. 틀릴 수도 있고 다를 수도 있고 변경될 수도 있다는 생각을 가진다는 게 정말 어렵지만 그럼에도 불구하고 좋은 제품과 서비스를 만들기 위해서는 필수의 자세인 것 같다.

 

의료기기의 인허가와 관련한 글쓰기

 의료기기를 인허가를 받기 위해서는 해당 의료기기가 사용자에게 적합하게 충분한 성능을 내면서 안전한지 확인해야 한다. 또 정말 의료기기가 앞에서 말한 사항을 만족하며 잘 제조되는지를 확인해야 한다. 이러한 확인은 검증된 기관에서 한다.(예를 들면 FDA, 식약처 등등) 기관이 인허가를 심사하기 위해서는 사용자에게 적합한지, 충분한 성능을 내는지, 안전한지 그리고 잘 만들어질 수 있는 프로세스가 있는지에 대한 관련 문서와 근거 자료로 확인받는다.

 여기서 관련 문서와 근거 자료들은 기본적으로 여러 규정에 따라 작성된다. 이러한 규정을 만족하는 문서를 작성해야 한다. 규정을 따르며 작성하되 몇몇 부분은 논리를 바탕으로 설득할 수 있게 근거 자료를 잘 작성해야 한다. 간단한 예를 들어보자. 안전을 위해 의료기기의 기능 동작 전 확인하는 기능이 있다. 여기서 확인을 수치를 기반으로 한다고 하자. 이때 이 수치를 왜 이렇게 선정하였는지 근거 자료로 논리를 만들어야 한다. 이 논리를 바탕으로 의료기기 인허가 심사 진행 시 설득할 수 있어야 한다.

 이러한 논리를 위한 근거 자료를 이전에 작성 경험을 설명한 기능 기획 및 제안서 그리고 실험 프로토콜 및 보고서를 응용한다. 이전에 언급한 인허가 관련 규정에 맞추어 작성 문서 양식이 조금 변경되기도 한다. 하지만 기능 기획 및 제안서 그리고 실험 프로토콜 및 보고서에서 작성된 내용을 잘 작성하였다면 이에 맞게 변경하는 것은 크게 어렵지 않다고 생각한다.

 

성장을 위한 글쓰기

 개인적인 성장을 위해서 책을 읽고 글을 쓰거나, 배운 지식에 대하여 정리를 하거나, 개발과 관련한 경험 및 방법을 블로그에 정리한다. 이 책의 '7장 기술 블로그 쉽게 쓰고 운영하기'에는 이와 관련하여 도움이 되는 부분들이 많이 작성되어 있었다. 이와 관련하여 글을 쉽게 쓰는 방법에 대한 부분을 요약하여 설명하고자 한다.

 첫 번째는 어떤 목표나 주제를 바탕으로 서술하는 것이 아니라 소재와 사전, 경험 등을 바탕으로 풀어내는 방법이다. 지식에 대한 정리나 개발에 대한 여러 자료 및 경험 정리는 어떤 주제가 없다. 그저 머릿속에 흩어져있는 그리고 필요할 때 다시 볼 수 있게 정리해두는 것이 더 중요하다.

 두 번째는 어떤 독자를 산정하고 그에 맞추어 글을 적는 것이 아닌 내가 이해할 수 있는 글을 쓰는 방법이다. 사실 나는 이 부분은 조금 동의하기가 어려웠다. 누구든지 쉽게 읽을 수 있는 글을 작성해야 된다고 생각하기 때문이다. 하지만 쉽게 글들을 작성하는 것이 목적이라면 먼저 내가 이해할 수 있게 작성하는 게 좋다. 이후 세세한 부분을 풀어서 글을 보완하면 다른 사람도 쉽게 글을 읽을 수 있기 때문이다. 한 번에 모두를 만족시킬 수 있는 마스터 피스를 작성할 필요는 없다.(그래도 여전히 읽기 쉽게 작성을 해야 한다는 생각이 많다.)

 세 번째로 재미있게 글을 쓰는 것이다. 말을 쉽지만 가장 어려운 부분이라고 생각한다. 그냥 생각나는 유머가 있다면 그러한 짤들과 힘을 함께 적절하게 작성하다 보면 글쓰기가 재미있을 것 같긴 하다. 하지만 현실은 조금 귀찮기 때문에 나는 재미있는 것들을 추가하지 않는 것 같다.

 

끊임없이 기록을 남기기

 어떤 기록이던 쓸모가 있다. 꼭 잘 작성한 것만이 쓸모 있는 게 아니다. 너무 잘못 적힌 것이 쓸모없는 것이 아니다. 잘 작성된 것은 그대로 의미가 있고 잘못 작성된 것은 고치면서 의미를 갖추게 된다. 하지만 어떤 기록이 작성조차 되어 있지 않다면 어떤 의미도 가질 수 없는 것 같다. 꾸준히 지속 가능한 방식으로 글들을 쌓아나가야겠다는 생각을 했다.