의외로 몰랐던 개발자의 글쓰기

 

세계적으로 유명한 컨설턴트이자 거래 및 투자 코치인 반 K.타프 박사는 ‘원하는 상태_Being’를 강조합니다. 무언가를 하거나 무언가를 소유하기 전에 ‘그런 상태’가 되어야, 그 원하는 것을 하거나 손에 넣을 수 있다는 뜻입니다.

개발된 프로그램의 코드만 읽어서는 개발자의 정확한 의도를 확인하기 어려운 경우가 많습니다. 이 때문에 프로그램 개발을 할 때 코드에 대한 주석을 강조합니다. 주석은 이유를 알려주고, 새롭게 발견한 것을 기록하고, 예상되는 질문에 대한 답을 미리 알려줍니다. 주의사항을 적기도 하고 추후 보완이나 개선사항을 준비하라고 시키기도 합니다. 이렇듯 주석을 통해 개발 의도를 전달하는 이유는 이 코드를 보는 다른 개발자를 위할 때가 많습니다. 이러한 마음이 있어야 주석을 제대로 잘 쓸 수 있습니다.

프로그램 코드는 비슷한 기능을 하는 것이 많습니다. 이 때문에 복사하여 붙여넣기를 한 뒤 수정하여 사용하는 경우 또한 많습니다. 이럴 때 주석도 같이 따라옵니다. 보통 코드는 수정하지만 주석은 그냥 지나치는 경우가 있습니다. 또 다른 예를 들어봅니다. 프로그램에 오류가 있으면 급하게 요청을 합니다. 개발자는 요청을 받아 급하게 오류를 수정합니다. 이 때 코드만 수정합니다. 주석은 그대로 남습니다.

이런 경우 많으시죠? 알고 있어도 잘 안되는 것이 사실입니다. 글을 쓴다는 것이 개발자 입장에서는 코드 보다 중요하지 않습니다. 또, 개발자는 글을 잘 못 쓴다고 생각하는 주위의 시선도 한몫 합니다. 개발자가 쓰는 글은 분명이 기존의 글과 다른 무언가가 필요합니다. 그 무언가를 원하는 상태가 되었다면 한번 제대로 배워보는 건 어떨까요?

 

개발자의 글쓰기 변수 네이밍부터 릴리스 노트, 장애 보고서, 기술 블로그까지, 프로그래머의 글쓰기 고민 끝!
김철수 저 | 위키북스 | 2019년 10월 04일

 

개발자가 쓰야 하는 글이 몇가지가 될까요? 단어와 문장 수준에서는 함수와 변수 등의 이름 짓기, 코드에 대한 주석쓰기, 에러 메시지 구분하기가 있습니다. 조금 더 길게는 릴리스 문서, 장애 보고서, 개발 가이드가 있습니다. 스토리를 담는 수주 제안서, 기술 블로그 등까지 나아갈 수 도 있습니다.

이 책은 이 같이 짧은 글에서 시작하여 수주 제안서 및 기술 블로그 작성까지 필요한 글쓰기 방법을 알려주는 책입니다. 개발자는 코드로 이야기 합니다. 하지만, 궁극적으로는 글로 소통할 줄 알아야 한다고 합니다. 글로 소통할 때 한단계 업그레이드 할 수 있다고 합니다. 정확성, 간결성, 가독성이 개발자 글쓰기에서 중요하다고 합니다. 이 기본을 익히기 위한 개발자의 글쓰기 교육이 별도로 필요하다는 것도 강조합니다.

이렇게 개발자의 글은 다르다라고 구분을 합니다. 하지만, 이렇게 나누더라도 글쓰기에는 가장 기본적인 원칙이 있습니다. 문장과 단락을 구조화하는 방법에 대한 이해가 필요합니다. 띄어쓰기와 문장 부호, 맞춤법을 지켜야 합니다. 특히 프로그램이 영어다 보니 외래어 표기법이 강조되기도 합니다.

중요한 것은 내용과 형식이 일치해야 한다는 것이다. 줄거리가 있는 설명이나 이야기라면 서술식으로 써야 한다. 여러 가지 종류의 항목과 내용이 반복되거나 서술식에서 강조가 필요한 내용이라면 개조식으로 써야 한다. 각 항목이나 사항의 관계를 명확히 규정하고 싶다면 도식으로 써야 한다.^29쪽

개발자의 마음가짐에 대한 이야기도 빼놓지 않습니다. 프로그램에 에러가 없을 수는 없습니다. 줄이기 위한 노력이 필요합니다. 그 방법 중 가장 좋은 것이 바로 사용자의 입장에서 이해하는 것입니다. ‘왜 시키는 대로 하지 않았냐?’가 안 통합니다. 시키지도 않은 일을 할 수 있다는 가정에서 고민해야 합니다.

모든 개발자는 사용자가 에러 없이 프로그램을 사용하게 만들고 싶어 한다. 하지만 에러가 한 번도 발생하지 않게 프로그램을 온전히 개발할 수 있는 개발자는 없다. 사용자마다 사용법이 제각각이고, 아무리 매뉴얼이나 도움말을 충실히 적어도 사용자가 무시하고 마음대로 사용하기 일쑤다.

그래서 에러를 줄이려면 개발자도 사용자의 사용 방식을 이해해야 한다. 사용자가 어떻게 사용할지를 충분히 이해하고 조사하고 분석해야 에러를 줄일 방법을 찾을 수 있다.^113쪽

개발자가 한 일에 대해서 기록하는 방법은 현실감 있는 예를 듭니다. 책은 한 일에 대한 정도를 어디까지 기록해야 할 지 딱 정해줍니다. 한 때 코미디 프로에서 유행한 코너가 생각하기도 합니다.

어떤 일을 하고 나서 그 일의 내용을 상사나 고객에게 글로 보고해야 할 때가 있다. 이때 글을 지나치게 줄여 쓰면 일을 안 한 것처럼 보인다. 그렇다고 해서 일의 내용을 하나씩 구체적으로 다 쓰면 아무도 읽지 않는다. 체인지 로그_changelog가 이런 경우에 해당한다. 간단히 쓰면 한 일이 없어 보이고 자세히 쓰면 아무도 읽지 않아 쓸모가 없다.^120쪽

최근 블로그나 유튜브를 통해 기술 지식을 많이 알리는 개발자가 많습니다. 의외로 개발자 세계에서는 Gㅕurr가 되길 바라는 사람이 많습니다. Guru가 아니더라도 개인 Branding 을 위해서, 알게된 지식을 정리하기 위해서, 배운 지식을 다른 사람과 공유하기 위해서라도 기술적인 글을 씁니다. 저자는 이러한 글을 쓸 때 필요한 지식 및 기준이 되는 이야기도 알려주고 있습니다.

일반적인 기획서나 보고서 같은 비즈니스 문서는 보고 대상이 누군지 정해져 있어서 대상에 맞춰 수준을 조절할 수 있다. 하지만 개발자가 쓴 개발문서의 독자는 매우 다양하다. 심지어 문서를 깃허브에 공개하면 전 세계 개발자가 읽는다.(중략)

좋은 방법은 기술의 범용성을 기준으로 하는 것이다. 만약 10년 전에 스마트폰 사용 매뉴얼을 썼다고 하자. 그때는 새로운 유저인터페이스를 아주 장황하게 기술했다. 그때는 초등학생이나 대학교수나 똑같은 수준이었다. 지금은 그냥 더블 클릭, 길게 클릭, 슬라이딩, 확대 같은 말만 써도 독자가 알아듣는다. 초등학생이나 대학교수나 모두 잘 이해한다.^198쪽

SI프로젝트 제안서 작성할 때 유의하면 좋은 예시도 많습니다.

책의 저자가 김철수로 소개됩니다. 필명이 아니라 본명이라면 기억하기 쉬울 듯 합니다. 국문학과를 졸업하고 개발자, 기획자, 컨설턴트, 강사 등으로 일을 했다고 합니다. 문과를 나와 이과 업무의 대표적 3D (?) 직업 경험이 이 책의 내용을 풍부하게 하는 것 같습니다. 주위에 문과를 나와 프로그램 개발을 하는 사람을 보면 기존 세계와 다른 다른 뭔가가 있습니다. 설명하기는 힘듭니다. 비전공자의 융합적 사고에 대한 탁월한 성과가 주목될 뿐입니다. 다만, 이 책을 보고 나니 아마 코드를 글로 이해하는 뭔가가 아닐까 하는 생각도 해봅니다.

개발자가 기술 블로그를 쓸 때는 독자를 생각해서 어려운 용어를 일부러 해석해 풀어쓰거나 쉬운 용어로 바꿀 필요가 없다. 원래 사용하는 용어로 그냥 표기하되 필요하다면 용어를 정의한 위키디피아 페이지나 세부 내용을 볼 수 있는 사이트나 문건을 링크로 걸어두면 된다. 기술 블로그란 것은 결국 실력이 비슷한 독자를 위한 것이다. 독자에게 다 설명하는 것이 아니라 핵심 내용만 쓰고 나머지는 독자가 공부할 수 있게 길만 터놓는 것이 현명한 방법이다. 그래야 개발자도 자기가 쓰려는 글의 본질에 집중할 수 있다.^239쪽

처음에도 말했듯이 개발을 해본 사람이라면 제일 처음 마주하는 것이 이름 짓기 일 것입니다. 개발 표준이 있는 회사라면 일정부분 참고할 수 있지만 그게 아니라면 처음부터 어떻게 해야 할 지 고민하게 마련입니다. 함수명, 변수명, 테이블명, 컬럼명 등등으로 시작합니다. 그 다음은 아마도 문서의 템플릿을 찾게 됩니다. 이러한 개발자의 고민을 같이 들어주는 것 같은 책이 바로 이 책입니다.

요즘 같은 융합의 시대, 코드만 잘 짜고 오류없는 프로그램을 만드는 것이 최종 목표가 아닙니다. 개발자 끼리를 넘어 수많은 이해관계자들에게 쉽게 설명할 수 있는 것이 필요합니다. 이때 필요한 보편적인 방법이 글쓰기 일 것입니다. 새로운 시대가 원하는 개발자가 되기 위해서는 새로운 시대가 원하는 것을 갖춰야 됩니다. 그렇게 되기를 원하는 상태라면 이 책은 충분히 동기부여가 될 것입니다.