<div id="readability-page-1" class="page"><div><figure><div role="button" tabindex="0"><p><img alt="" src="https://miro.medium.com/max/12000/1*B_7lJQZsJbrSOlrs_yDJjg.jpeg" width="6000" height="4000" role="presentation"></p></div><figcaption>Photo by <a href="https://unsplash.com/@thoughtcatalog?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText" rel="noopener nofollow">Thought Catalog</a> on <a href="https://unsplash.com/s/photos/developer-writing?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText" rel="noopener nofollow">Unsplash</a></figcaption></figure><div><h2 id="fa1d">개발자 글쓰기의 어려움</h2><div><p><a rel="noopener" href="/?source=post_page-----ee7a4204dd0a--------------------------------"><img alt="Beejei Kim" src="https://miro.medium.com/fit/c/56/56/0*uqVHtuzJjYbj_uOG.jpeg" width="28" height="28"></a></p></div></div><p id="8fe1">글을 쓰는 것은 어렵다. 이 말은 내가 글쓰기 플랫폼을 열어 두고 늘 하게 되는 탄식이기도 하다. 언제나 글을 쓰는 것은 어렵고 부담스러운데, 왜 어려운지까지 생각이 이어지다가 최근에서야 그 이유를 두 가지 알게 되었다. 한가지는 내가 단어나 표현의 정확한 의미를 잘 모르는 채 글을 쓰고 있었다는 점이고, 다른 한가지는 내가 떠오르는 인상이나 감정이 정확히 어떤 것인지 구분할 수가 없었다는 점이다.</p><p id="c81e">아마 첫번째 이유는 세상에 더 정확한 사전이 있고 그것을 통해 혼동이 있을<span id="rmm"><span id="rmm"> </span></span>때마다 더 표현을 갈고 닦으면 해결되리라 생각한다. 그런데 두 번째 이유는 그렇게 시스템적으로 해결할 수가 없다. 좀 더 다른 사람의 글을 보고, 다른 사람의 컨텍스트와 감상을 이해하고, 실제로 그것들을 구분해보고 나의 그것과 맞추어 보지 않는 한 더 나은 구분을 하기가 어렵다.</p><p id="921a">그럼에도 불구하고 한자 적어 내려가는 것을 주저한다면 평생 가더라도 글을 게시하는 일은 없을 것이다. 어디까지나 정도의 차이가 있을 뿐, 어렴풋하게 떠오르는 감상을 가지고 가까스로 기억해낸 남들의 표현을 빌어 글을 계속 써내려가 보는 수 밖에 없다.</p><p id="4dea">개발자의 글쓰기를 계속 고민하면서 위의 “모호성”에 대해 한번 더 깨우치는 계기가 되었다. 개발자가 글을 쓰기는 하겠으나, 그것이 “누구”를 위한 “어떤 내용”을 품은 글이란 말인가? 아마 시작은 코드 옆에 주석으로 잔뜩 적어내리던 내용을 좀 더 알기 쉽게 별도의 문서로 어떤 매니저가 지시한 것에서부터 시작하지 않았나 싶다. 그러다가 또하나의 천재적인 개발자가 “문서로서의 코드”와 “자동 문서 생성”을 주창하며 기술 문서 자동 제너레이션과 정적 사이트 생성기가 마치 표준인 것 처럼 이야기되고 있다.</p><p id="6faf">최근에 “<a href="https://lazygyu.net/blog/secrets_of_documentation" rel="noopener nofollow">문서화에 대해 아무도 말해주지 않는 것들</a>"을 읽고 뒤통수를 세게 두드려 맞는 느낌이 들었다. 글이란 건 독자(청자)에 맞추어 써야 하고, 그에 따라 글의 목적이 달라지며, 글의 목적이 달라진다는 건 여러 벌의 글을 써야 한다는 의미이기도 하다. 애초에 “글을 쓰라"고만 하였지, “어떻게"에 대해 한번도 들어보지 못한 상황에서, 수십년의 경력이 녹아있는 제대로 된 문제를 지적하는 글이었다고 생각한다(<code>First step in solving any problem is recognizing there is one</code>). 하지만 코드를 작성하기도 시간이 부족한 개발자가 여러 벌의 글을 무슨 재주로 없는 실력으로 만들어 낸단 말인가? 결론부터 말하자면 그건 불가능하다 - 몇몇의 개발 외적으로도 천재적인 일부의 사람들을 제외하고는 (존경합니다) -.</p><p id="fabe">하지만 불가능한 일이어도 무엇때문에 왜 불가능한지는 알아야한다. 사실 대부분의 개발자들이 퍼펙트한 코드는 짜지 못해도 뭘 못하는지는 알지 않는가.</p><p id="7fe7"><strong>1.Source code와 함께 작성하는 개발자간 공유 용도의 문서</strong></p><p id="4a2c">일단 소스 코드를 작성하면서 주석으로 달 법한 내용은 두 가지가 있다. 첫째는 구조체나 함수의 명세를 적는 일이다. 이것은 인텔리센스와 연계되어 도움말을 줄 수도 있고, JSDoc 같은 툴로 명세 레퍼런스를 별도 문서나 정적 사이트로 만들수도 있다. 타겟은 이 코드를 그대로 공유받을 또다른 협업 개발자, 혹은 그 구조체와 펑션을 이용할 스테이크홀더로서의 개발자가 될 수 있겠다. 두번째는 알고리즘의 내용을 기술하는 문서다. 소스코드가 그 자체로 설명 불가능한 경우, 보조적인 내용이 반드시 기술되어야 한다. 가령 일부러 이중포인터를 써서 메모리 접근 속도를 최적화한다던가, 미리 잡아놓은 메모리 공간을 일부러 환원하지 않고 계속 재활용해야 한다던가. 알고리즘이 곧 비즈니스 로직이 아니어서 선언적인 내용이 매핑되기 어려운 경우 추가적인 기술이 필요하다. 아마도 이미지, 슬라이드, 다이어그램 등의 별도 공간이 필요한 문서가 될 확률이 높은데 이걸 잘 작성하거나 적절히 넣어두기 좋은 공간은 아직 찾지 못했다. (아마도 Wiki?)</p><p id="2d2f"><strong>2.프로젝트 소개 및 구조에 대한 문서</strong></p><p id="eb7e">그 다음으로 필요한 문서는 프로젝트 자체를 설명하기 위한 문서다. 아마 프로젝트 리더, 혹은 매니저로써 작성해야 하는 문서일텐데 보통은 외부의 요청 내용과 맞추어 작성될 수 밖에 없다. 또한 아키텍쳐를 그리더라도 다른 팀의 시스템과 연계해서 그려야 하기 때문에 그림 자체가 상당히 커지고 내용도 종속적이다. 문제는 앞선 테크니컬한 문서야말로 개발자들이 공을 들이고 작성해야 한다고 생각할 확률이 높지만, 오히려 이 문서들이 팀의 존속을 위해서 더 필요하다는 점이다. 일종의 팀의 존재 이유를 설명하는 문서가 될 수도 있기 때문이다. 따라서 설명 그 자체만 담담하게 넣는 경우도 있지만 여기서부터는 좀 더 보기 좋게 꾸며보지 아니할 수가 없다. 거기에 구현될 기능 별로 예상 스케쥴(estimation)을 넣어야 하기 때문에 각종 프로젝트 관리 툴들과 내용이 일치되어야 해서 변경이 있을 때마다 스트레스를 받기도 한다.</p><p id="feea"><strong>3.프로덕트 소개 및 그 일부로서의 프로젝트에 대한 문서</strong></p><p id="9596">그다음으로 필요하다면 우리의 일을 처음부터 보는 사람을 위한 문서를 만들어야 한다. 그 대상은 내 가족이 될 수도 있고, 새로 부임한 높으신 매니저분이 될 수도 있고, 우리와 처음 협업을 시작하는 다른 회사의 디자인팀이 될 수도 있다. 나무 한 두 그루를 가꾸는 개발자로 종사하다가 숲을 소개해야 하는 어처구니없는 일이 생각보다는 자주 일어난다. 여기서 부터는 생각해야 할 일이 너무 많다. 우리가 제공하려고 하는 혜택이 무엇이었는지 부터 시작해서, 현재 얼마만큼 진행되었는지, 언제 쯤에 완결이 가능한지, 우리말고 대채제는 정말 없는지, 우리가 경쟁프로젝트보다 얼마나 더 필요한지, 우리가 사용하는 표현이 그들에게 똑같이 이해가 가능한지까지 신경써야 한다.</p><p id="f0ad">이 부분은 꽤 오랫동안 고민하다가 솔직히 약간 포기했다. 이부분은 정말 글을 세련되게 잘 쓰고, 표현 하나하나에 신경쓸 수 있는 전문 라이터들의 영역이라고 생각된다. 우리 프로덕트가 시장에서 어떤 의미가 있는지는 매니저들이 좀 더 고민할 영역이고(보통 그들이 가장 큰 영향을 받게 되므로), 어떻게 잘 꾸며서 보여줄지도 개발자가 하기에는 한계가 있다. 그럼에도 불구하고 잘 해보고 싶다면 남의 템플릿을 빌려보는 게 가장 의미있을 것 같다.</p><p id="d3c7">부끄럽지만 MS나 Slack 등의 수많은 팬을 보유하고 하루가 멀다하고 새로운 뉴스거리가 생겨나는 프로젝트의 사이트를 참고해 보자. 미천한 영어 실력도 그들의 표현을 최대한 빌려 우리가 내고 싶은 표현의 온도를 가늠해서 차용해 보자. 디자인은 정적 사이트 생성기의 너무 튀지 않는 디자인 템플릿을 이용해서 글조각과 디자인을 재조립해 보기로 한다. 일부 정적 사이트 테마의 경우 너무 블로그나 CMS의 형태를 띄우고 있으므로 소개글을 배열하기 좋은 템플릿으로 골라 본다.</p><h2 id="d5a8"><strong>끝으로</strong></h2><p id="c901">모든 사람이 글이 다 잘 쓸수는 없다. 글을 잘 쓰는 사람들은 아마도 개발자가 개발에 쓰는 배움의 시간 만큼 지금도 글을 배우고 있을 것이다. 그렇다고 글쓰기의 시작을 마냥 미루기만 할 수도 없다. 큰 부담 없이 가능한 적정 선에서 시작해 보면, 언젠가 천재들의 훌륭한 역량을 좀 더 쉽게 흉내낼 수 있는 날이 오지 않을까.</p></div></div>

Stories by Beejei Kim on Medium

글을 쓰는 것은 어렵다. 이 말은 내가 글쓰기 플랫폼을 열어 두고 늘 하게 되는 탄식이기도 하다. 언제나 글을 쓰는 것은 어렵고 부담스러운데, 왜 어려운지까지 생각이 이어지다가 최근에서야 그 이유를 두 가지 알게 되었다. 한가지는 내가 단어나 표현의 정확한 의미를 잘 모르는 채 글을 쓰고 있었다는 점이고, 다른 한가지는 내가 떠오르는 인상이나 감정이 정확히 어떤 것인지 구분할 수가 없었다는 점이다.
아마 첫번째 이유는 세상에 더 정확한 사전이 있고 그것을 통해 혼동이 있을 때마다 더 표현을 갈고 닦으면 해결되리라 생각한다. 그런데 두 번째 이유는 그렇게 시스템적으로 해결할 수가 없다. 좀 더 다른 사람의 글을 보고, 다른 사람의 컨텍스트와 감상을 이해하고, 실제로 그것들을 구분해보고 나의 그것과 맞추어 보지 않는 한 더 나은 구분을 하기가 어렵다.
그럼에도 불구하고 한자 적어 내려가는 것을 주저한다면 평생 가더라도 글을 게시하는 일은 없을 것이다. 어디까지나 정도의 차이가 있을 뿐, 어렴풋하게 떠오르는 감상을 가지고 가까스로 기억해낸 남들의 표현을 빌어 글을 계속 써내려가 보는 수 밖에 없다.
개발자의 글쓰기를 계속 고민하면서 위의 “모호성”에 대해 한번 더 깨우치는 계기가 되었다. 개발자가 글을 쓰기는 하겠으나, 그것이 “누구”를 위한 “어떤 내용”을 품은 글이란 말인가? 아마 시작은 코드 옆에 주석으로 잔뜩 적어내리던 내용을 좀 더 알기 쉽게 별도의 문서로 어떤 매니저가 지시한 것에서부터 시작하지 않았나 싶다. 그러다가 또하나의 천재적인 개발자가 “문서로서의 코드”와 “자동 문서 생성”을 주창하며 기술 문서 자동 제너레이션과 정적 사이트 생성기가 마치 표준인 것 처럼 이야기되고 있다.
최근에 “문서화에 대해 아무도 말해주지 않는 것들"을 읽고 뒤통수를 세게 두드려 맞는 느낌이 들었다. 글이란 건 독자(청자)에 맞추어 써야 하고, 그에 따라 글의 목적이 달라지며, 글의 목적이 달라진다는 건 여러 벌의 글을 써야 한다는 의미이기도 하다. 애초에 “글을 쓰라"고만 하였지, “어떻게"에 대해 한번도 들어보지 못한 상황에서, 수십년의 경력이 녹아있는 제대로 된 문제를 지적하는 글이었다고 생각한다(First step in solving any problem is recognizing there is one). 하지만 코드를 작성하기도 시간이 부족한 개발자가 여러 벌의 글을 무슨 재주로 없는 실력으로 만들어 낸단 말인가? 결론부터 말하자면 그건 불가능하다 - 몇몇의 개발 외적으로도 천재적인 일부의 사람들을 제외하고는 (존경합니다) -.
하지만 불가능한 일이어도 무엇때문에 왜 불가능한지는 알아야한다. 사실 대부분의 개발자들이 퍼펙트한 코드는 짜지 못해도 뭘 못하는지는 알지 않는가.
1.Source code와 함께 작성하는 개발자간 공유 용도의 문서
일단 소스 코드를 작성하면서 주석으로 달 법한 내용은 두 가지가 있다. 첫째는 구조체나 함수의 명세를 적는 일이다. 이것은 인텔리센스와 연계되어 도움말을 줄 수도 있고, JSDoc 같은 툴로 명세 레퍼런스를 별도 문서나 정적 사이트로 만들수도 있다. 타겟은 이 코드를 그대로 공유받을 또다른 협업 개발자, 혹은 그 구조체와 펑션을 이용할 스테이크홀더로서의 개발자가 될 수 있겠다. 두번째는 알고리즘의 내용을 기술하는 문서다. 소스코드가 그 자체로 설명 불가능한 경우, 보조적인 내용이 반드시 기술되어야 한다. 가령 일부러 이중포인터를 써서 메모리 접근 속도를 최적화한다던가, 미리 잡아놓은 메모리 공간을 일부러 환원하지 않고 계속 재활용해야 한다던가. 알고리즘이 곧 비즈니스 로직이 아니어서 선언적인 내용이 매핑되기 어려운 경우 추가적인 기술이 필요하다. 아마도 이미지, 슬라이드, 다이어그램 등의 별도 공간이 필요한 문서가 될 확률이 높은데 이걸 잘 작성하거나 적절히 넣어두기 좋은 공간은 아직 찾지 못했다. (아마도 Wiki?)
2.프로젝트 소개 및 구조에 대한 문서
그 다음으로 필요한 문서는 프로젝트 자체를 설명하기 위한 문서다. 아마 프로젝트 리더, 혹은 매니저로써 작성해야 하는 문서일텐데 보통은 외부의 요청 내용과 맞추어 작성될 수 밖에 없다. 또한 아키텍쳐를 그리더라도 다른 팀의 시스템과 연계해서 그려야 하기 때문에 그림 자체가 상당히 커지고 내용도 종속적이다. 문제는 앞선 테크니컬한 문서야말로 개발자들이 공을 들이고 작성해야 한다고 생각할 확률이 높지만, 오히려 이 문서들이 팀의 존속을 위해서 더 필요하다는 점이다. 일종의 팀의 존재 이유를 설명하는 문서가 될 수도 있기 때문이다. 따라서 설명 그 자체만 담담하게 넣는 경우도 있지만 여기서부터는 좀 더 보기 좋게 꾸며보지 아니할 수가 없다. 거기에 구현될 기능 별로 예상 스케쥴(estimation)을 넣어야 하기 때문에 각종 프로젝트 관리 툴들과 내용이 일치되어야 해서 변경이 있을 때마다 스트레스를 받기도 한다.
3.프로덕트 소개 및 그 일부로서의 프로젝트에 대한 문서
그다음으로 필요하다면 우리의 일을 처음부터 보는 사람을 위한 문서를 만들어야 한다. 그 대상은 내 가족이 될 수도 있고, 새로 부임한 높으신 매니저분이 될 수도 있고, 우리와 처음 협업을 시작하는 다른 회사의 디자인팀이 될 수도 있다. 나무 한 두 그루를 가꾸는 개발자로 종사하다가 숲을 소개해야 하는 어처구니없는 일이 생각보다는 자주 일어난다. 여기서 부터는 생각해야 할 일이 너무 많다. 우리가 제공하려고 하는 혜택이 무엇이었는지 부터 시작해서, 현재 얼마만큼 진행되었는지, 언제 쯤에 완결이 가능한지, 우리말고 대채제는 정말 없는지, 우리가 경쟁프로젝트보다 얼마나 더 필요한지, 우리가 사용하는 표현이 그들에게 똑같이 이해가 가능한지까지 신경써야 한다.
이 부분은 꽤 오랫동안 고민하다가 솔직히 약간 포기했다. 이부분은 정말 글을 세련되게 잘 쓰고, 표현 하나하나에 신경쓸 수 있는 전문 라이터들의 영역이라고 생각된다. 우리 프로덕트가 시장에서 어떤 의미가 있는지는 매니저들이 좀 더 고민할 영역이고(보통 그들이 가장 큰 영향을 받게 되므로), 어떻게 잘 꾸며서 보여줄지도 개발자가 하기에는 한계가 있다. 그럼에도 불구하고 잘 해보고 싶다면 남의 템플릿을 빌려보는 게 가장 의미있을 것 같다.
부끄럽지만 MS나 Slack 등의 수많은 팬을 보유하고 하루가 멀다하고 새로운 뉴스거리가 생겨나는 프로젝트의 사이트를 참고해 보자. 미천한 영어 실력도 그들의 표현을 최대한 빌려 우리가 내고 싶은 표현의 온도를 가늠해서 차용해 보자. 디자인은 정적 사이트 생성기의 너무 튀지 않는 디자인 템플릿을 이용해서 글조각과 디자인을 재조립해 보기로 한다. 일부 정적 사이트 테마의 경우 너무 블로그나 CMS의 형태를 띄우고 있으므로 소개글을 배열하기 좋은 템플릿으로 골라 본다.
끝으로
모든 사람이 글이 다 잘 쓸수는 없다. 글을 잘 쓰는 사람들은 아마도 개발자가 개발에 쓰는 배움의 시간 만큼 지금도 글을 배우고 있을 것이다. 그렇다고 글쓰기의 시작을 마냥 미루기만 할 수도 없다. 큰 부담 없이 가능한 적정 선에서 시작해 보면, 언젠가 천재들의 훌륭한 역량을 좀 더 쉽게 흉내낼 수 있는 날이 오지 않을까.

개발자 글쓰기의 어려움

댓글