개발과 기술 글쓰기

이번 칼럼에서는 기술 글쓰기에서 중요한 몇 가지 요소를 살펴봅니다.

글ㆍ사진 박찬성(프로그래머)

2022.08.08

작게

크게

언스플래쉬

개발자가 갖춰야 하는 가장 중요한 역량은 결국 '개발'입니다. 출중한 개발 능력이야말로 제품의 기능을 하자 없이, 정해진 기한 내에 만들 수 있기 때문입니다. 그런데 개발 역량은 어떻게 키울 수 있을까요? 많은 연습만이 답일지도 모릅니다.

하지만 내가 연습하는 방향이 올바르고 합리적이라는 것은 어떻게 확신할 수 있을까요? 그 해답 중 하나는 '글쓰기'입니다. 특히, 본인의 이름을 걸고 불특정 다수에게 읽힐 공개 글을 작성하는 것이 중요합니다. 이번 칼럼에서는 기술 글쓰기에서 중요한 몇 가지 요소를 살펴봅니다.

기술 글쓰기란?

기술 글쓰기는 말 그대로 기술에 대해 글을 쓰는 행위입니다. 그리고 모든 글이 그러하듯이 청중에 따라 다른 방식으로 작성될 수 있습니다. 가령, 프로그램 사용자에게는 API 수준의 문서를, 프로그램 개발의 참여자 또는 잠재적 기여자에게는 내부 구현 세부 사항의 문서를, 프로젝트 방향의 결정자에게는 전체 그림에 대한 설계 문서를 작성할 수 있습니다. 같은 프로젝트여도, 바라보는 눈높이와 관심사에 따라 설명 방식과 포함될 내용이 다를 수 있습니다. 다만, 이와는 무관하게 기술 글쓰기라면 따라야 좋을 몇 가지 공통 사항이 있습니다.

1. 기승전결의 흐름
2. 핵심 기술과 주변 기술의 분배
3. 짧고 명료한 논리적 무결성
4. 핵심을 요약하는 그림
5. 근거 자료의 첨부

1. 기승전결의 흐름

모든 글은 자신만의 이야기를 가지고 있는 편이 좋습니다. 이를 기승전결의 흐름에 빗대어 설명해 볼 수 있습니다.

'기(起)' 부분은 청중이 배경지식 및 문제의식을 습득할 수 있도록 작성합니다. 꽤 간과되는 경우가 많지만, 청중과 공감대를 형성하기 위해 매우 중요합니다. 단순히 코드를 '복사/붙여넣기'하더라도 문맥이 없거나 부족하다면, 예상과는 다른 방식으로 작동하더라도 그 이유를 찾는 데까지 오랜 시간을 허비해야 할지도 모릅니다.

'승(承)' 부분은 '기(起)'에서 제기된 문제를 해결하기 위한 핵심 아이디어/기술을 이어서 설명하되, 깊은 내용을 포함하는 것이 좋습니다. 적당한 논리는 오히려 허점을 만들어낼 수 있기 때문에, 구석구석 논리적 무결성을 보여주기 위한 구체적인 내용의 설명이 필요합니다.

'전(轉)' 부분은 글 전반에 퍼져있습니다. 핵심 기술의 설명에 집중하는 게 좋지만, 단일 기술만으로 모든 설명이 가능한 상황은 현실적으로 존재하지 않습니다. 따라서 핵심 기술의 타당성을 설명하는 데 있어 그 주변의 기술도 챙기는 것이 좋습니다.

그리고 마지막 '결(結)' 부분은 모든 설명을 종합하여 최종 결론을 도출합니다.

2. 핵심 기술과 주변 기술의 분배

교과서적으로 특정 기술들에 대한 일반적이 설명을 담는 문서가 아니라면, 직면한 특정 상황과 문제를 부각하여 어떤 노력과 기술로 해당 문제를 풀었는지 설명하는 편이 좋습니다. 그 이유는 특정 상황의 문제라고는 해도 동종의 현업자들은 구체적인 세부 사항에만 차이가 있을 뿐, 유사한 문제에 직면하는 경우가 많고, 다른 현업자들이 해당 문제를 푼 구체적인 방식을 알고 싶기 때문입니다.

이 과정에서 문제를 해결한 핵심 아이디어와 기술을 집중적으로 설명해야 합니다. 하지만 한 가지 주의해야 할 점은 그 밖의 주변 기술을 설명하는데도 신경을 많이 써야 한다는 것입니다. 다만 주변 기술을 집중적으로 파고든 것이 아니기 때문에, 글을 쓰는 시점에 관련 내용을 더 파악하려고 하다 보면 지나치게 글을 길어지게 만들어서 논점을 흐리는 결과를 초래할 수도 있습니다.

가령 지속적인 머신러닝 모델의 서비스를 위한 MLOps 시스템을 GitHub 기반으로 구현하되 내부적으로 여러 오픈 소스를 통합했다면, 세부 컴포넌트에 대한 일반적인 설명은 생략하고 레퍼런스용 링크를 남겨두는 것이 바람직합니다. 그 대신 각 컴포넌트를 통합한 방식, 그러면서 필수적으로 언급될 수밖에 없는 타 컴포넌트의 특정 부분에 대한 설명, 그러면서 추가로 개발된 라이브러리의 세부 사항 등을 설명하는 편이 좋습니다.

어려운 내용을 쉽게 풀어서 다시 설명하는 것도 좋을 수 있지만, 대부분 공식 문서로 설명이 충분한 경우가 많으며, 오히려 무수히 생산되는 수많은 글마다 약간씩 다른 설명 때문에 혼란이 초래될 수 있습니다.

3. 짧고 명료한 논리적 무결성

기술 글쓰기에서 가장 중요한 요소는 아마도 논리적 무결성일 것입니다. 그리고 이 논리적 무결성은 반드시 레퍼런스, 육안으로 확인 가능한 실험 및 운영 결과, 의사 코드 또는 (되도록이면) 핵심 부분으로만 요약된 실제 코드 등이 포함되어야만 의미를 가질 수 있습니다. 단순히 말만 늘어놓는 방식은 뜬구름을 잡는 느낌을 줘서 오히려 혼란을 가중할 수 있으며, 최악의 경우에는 배움의 시작을 방해할 정도의 두려움까지 생기게 만들지도 모릅니다.

반면, 기술자들이 친숙한 실제 코드, 실제 아키텍처를 눈으로 확인할 수 있도록 해준다면, 그 글의 신뢰도는 꽤 높아집니다. 만약 친숙하지 않은 기술들이 사용되었다면, 기본 배경지식을 습득할 수 있도록 레퍼런스를 반드시 제공하는 편이 바람직합니다.

또한, 논리적으로 문제가 없지만, 실제로 코드가 실행되거나 설계된 시스템이 운영되는 상황과 환경에 따라 머릿속으로 그려본 논리와 실제 결과에 차이가 발생할 수 있습니다. 따라서 어떤 식으로든(예. 스크린샷, 정량적 지표 등) 그 결과를 확인할 수 있는 내용 정도는 반드시 포함하는 것이 좋습니다. 또는 동일한 환경을 구성하고, 동일한 단계로 시도하여 재현 가능한 수단을 제공할 수 있다면 가장 좋습니다.

한편, 대부분의 설명은 짧고 명료하게 작성되어야 합니다. 호소력을 짙게 만들기 위해서, 다양한 수식어와 부연 설명 등이 포함되는 것은 꽤 흔히 발생하는 잘못된 글쓰기 방식입니다. 수식어는 글 전체를 풍성하게 만들어주지만, 동시에 사람마다 다른 식으로 해석할 수 있는 여지도 만들어줍니다.

물론, 기술도 상황에 따라 다르게 해석될 수도 있지만, 특정 목적을 가진 기술 글쓰기 에서는 모두가 동일하게 글을 이해할 수 있도록 작성하는 것이 바람직합니다. 가령, 표준 통신 프로토콜 문서를 읽는 사람마다 다르게 해석한다면, 표준이지만 표준으로 사용되기 어려운 이상한 일이 일어날 수 있을 것입니다.

4. 핵심을 요약하는 그림

“그림에는 천 마디 단어가 담겨있다(A picture is worth a thousand words)”는 말이 있습니다. 사람은 그림 속에 숨겨진 수많은 의미를 함축적으로, 그러나 순식간에 무의식적으로 이해합니다. 따라서 그림을 적절히 활용하기만 한다면, 이해와 공감대를 더 깊은 곳까지 이끌어낼 수 있습니다. 결론적으로, 특정 기술 글을 읽고 나서 머릿속에 남는 것은 핵심을 관통하는 몇 개의 문장과 글 전체를 요약한 잘 그려진 그림 한 장이 되기 때문에, 그림은 매우 중요한 요소임이 틀림없습니다.

다만 몇 가지 주의해야 할 점이 있습니다. 간혹 상세한 메커니즘을 설명하는 그림을 가장 첫 부분에 넣는 경우가 있습니다. 이 경우, 제목만 보고 글을 읽기도 전에 사람마다 다양한 추측을 하게 됩니다. 그리고 사람마다 전문 분야에 따라, 부각되어 보이는 부분과 해석 방식이 말도 안 되게 달라지는 경우가 많습니다. 따라서 도입 부분에는 심각할 정도의 추측은 하지 않지만, 궁금증을 자아낼 정도의 매우 간단한 그림을 배치하는 편이 좋습니다.

대신, 정말 중요한 그림은 어느 정도 설명이 진행된 다음 배치하는 것이 바람직합니다. 문맥을 따라 글을 읽다 보면, 간혹 내용의 방대함 또는 복잡함에 압도되는 경우가 있습니다. 이 적절한 시점에 적절한 그림을 삽입하면, 자연스럽게 머릿속에 복잡하게 얽힌 지식을 정리할 수 있습니다. 여기서 주의할 점은, 그림에는 실제 글에 없는 내용, 내가 잘 이해하지 못한 내용이 포함되지 않도록 해야 합니다. 간혹 핵심에서 약간 벗어난 내용 중 내가 이해하지 못한 것을 그림에 포함시키는 경우가 있는데, 이런 행위는 결국 글 전체의 타당성을 흐리는 결과를 초래하여 신뢰도를 낮추게 됩니다.

5. 근거 자료의 첨부

마지막으로 사소하지만, 꼭 고려해야만 하는 두 가지 내용이 있습니다.

첫 번째는 서식의 통일성입니다. 기본적으로 모든 기술 글쓰기에는 일반 텍스트, 코드 텍스트, 그림에 포함되는 각종 아이콘과 도형이 포함됩니다. 가독성을 위해 일반 텍스트의 서식이 일관성을 가져야 함은 물론, 각종 언어와 스크립트에 대한 코드의 문법 하이라이트, 그리고 기술자들 간의 약속처럼 사용되는 아이콘과 도형을 임의로 바꾸는 것은 되도록 지양해야 합니다.

두 번째, 되도록 리뷰를 받을 수 있는 방법을 찾는 것이 좋습니다. '코드 리뷰 시스템(예. Git)'을 활용하여 여러 기술자 간의 피어 리뷰를 주고받을 수 있다면 지속적인 글쓰기가 가능할 수 있습니다. 다만 이를 위한 구성원을 구하는 것이 어렵다면, 전문적인 블로그 플랫폼의 저자로서 활동하는 것도 좋은 생각입니다. 가령, '미디움'의 다양한 퍼블리셔, 구글 클라우드 플랫폼의 공식 블로그 플랫폼을 통해 글을 발행하는 것이 가능하며, 그 과정에서 관련 기술 전문가들로부터 서식, 문법, 기술적 내용에 대한 리뷰를 받을 수 있습니다. 이러한 리뷰 시스템을 거쳐 발행된 글은 높은 신뢰도를 줄 수 있을 뿐만 아니라, 글쓴이의 기술 글쓰기 능력과 생각의 과정 등의 능력을 대폭 향상시켜줍니다.