소프트웨어테스팅버그 보고

[테스팅 실무] 더 나은 버그 보고를 위한 테스터의 글쓰기 3편

, , , , , , , ,

이번 편은 좋은 글을 쓰는 방법에 대해 세 가지 정도를 소개한다. 모두 글쓰기 시 알고 있으면 좋은 내용들이다.

필자는 실무에서 Technical Writer(테크니컬 라이터)로서 혹은 다른 여러 직무를 수행하면서 업무에 필요한 글쓰기를 하거나, 개인 취미로 블로그에 글쓰기를 하는 사람이다. 그러니 필자가 하는 조언만으로 글쓰기를 잘 할 수는 없다. 이렇게 미리 한 발 빼는 이유는 겸손한 척 하려는게 아니라 필자는 전문적으로 국어를 연구하거나, 학문적으로 글쓰기에 대해 연구해서 남을 가르치는 사람이 아니라는 이야기를 하고 싶은 거다. 그러므로, 더 전문적인 지식이 필요한 경우 본 포스팅 하단의 참고 자료를 참고하거나, 서점에서 더 좋은 글쓰기 관련 책들을 찾아 보시기를 권장한다.

3편을 시작하기 전에… 1편, 2편도 되게 흥미진진-스펙타클하지는 않았지만, 3편은 특히 더 어렵거나 지루하게 느껴질 수 있다. 하지만 3편의 내용을 명확히 습득하지 않고 이후로 넘어가면 결국 또 기본기 없이 요령만 배우는 꼴이 될 수 있으니, 어렵고 지루하더라도 3편을 꼭 잘 읽어보시기를 바란다.


좋은 문장 만들기

한국어는 문장 구성이 다른 언어에 비해 굉장히 자유로운 편에 속한다. 한국어의 문장은 주어, 동사, 목적어의 전후 위치를 변경해도 말이 잘 통한다. 그럼에도 불구하고 어느 정도 일반적이라고 통용되는 ‘좋은 글쓰기’의 규칙은 당연히 존재한다. 일단, 국어의 문장은 일반적으로 주어-목적어-서술어의 구조로 구성된다. 이런 기본적인 구조의 틀에 맞는 문장을 쓰는 게 좋은 문장을 만드는 핵심이다.

한국어라는 언어가 워낙 문장 구성이 다채롭게 변할 수 있는 유연성을 가진 언어이다 보니 그 사회의 글쓰기 문화에 따라 글의 형태가 많이 바뀌는 현상이 보인다. 인터넷이나 메신저에서 글 쓰는 데에 익숙해진 사람들은 본인의 주장이나 글의 목적을 문장의 서두에 배치해서 글의 구조가 복잡해지거나, 혹은 남을 불필요하게 지적하는 방식의 글쓰기 성향을 보인다. 혹은 (토론할 상황이 전혀 아닌 데도 불구하고) 남과 토론하듯이 따지고 드는 듯한 느낌의 글쓰기를 많이 하는 현상이 보이는데 이는 정말 좋지 않은 글쓰기 습관이다.

자, 글쓰기에 대한 기본기를 잘 갖추고 있다면, 회사에 다니며 사회생활을 할 때 많은 도움이 된다. 특히 외부의 고객과 글을 주고받아야 하는 회사의 직무를 수행하고 있다면 좋은 문장을 만들어 글을 쓰는 능력은 정말 중요한 핵심 역량이다. 그 회사에서는 그런 역량을 갖춘 사람들이 쓰는 글이 고객들에게 가치를 전달하며 수익을 창출할 수 있기 때문이다. 가치가 전달되어야 고객들이 지갑을 열고, 결과적으로 회사의 매출을 높이도록 하는 데 일조할 수 있는 중요한 인력이 바로 글쓰기를 잘하는 인력이다.

회사에서 ‘돈을 번다’는 행위는 고객에게 가치를 전달하고, 그 가치만큼의 금전적 재화를 청구하여 회사로 가져오는 활동을 말한다. 그러므로 돈을 벌기 위한 행위를 하는 모든 사람은 자신의 업무 성과를 글로 표현해야 할 필요가 있다. 돈 벌기를 위한 글쓰기를 할 때는 네 가지를 명심해야 좋은 문장을 만들 수 있다. ①정확하고, ②명료하게 그리고 ③간결하고, ④전문성을 담고 있도록 문장을 구성해야 한다. 그리고 본인의 글을 읽을 ‘대상 독자’가 누구인지를 명확히 해야 한다. 이에 대한 부분은 이후 4편, 5편에서 추가로 언급하겠다.

2022년, 너무나도 편리한 세상이다. 디지털 문화는 세상을 뒤덮고, 인류는 전에 볼 수 없던 속도로 온갖 새롭고 훌륭한 신문물들을 창조해내고 있다. 책 대신 좋은 영상들이 사람들의 여가를 차지했고, 뭔가를 정리하는 글쓰기 대신 댓글로 짤막하게 본인의 의견을 표출해낸다. 좋은 문장은 점점 그 가치를 잃어가고 메신저의 짤막한 글들이 대신 그 가치의 지위를 얻었다.

그렇게 변해간 세상에서 그에 대한 반대급부로 사람들은 점점 더 책을 읽지 않게 되는 듯하다. 책을 많이 읽어 좋은 문장을 만들어 낼 수 있는 사람과 그렇지 않은 사람 간의 차이는 21세기 중반으로 넘어가면서 점점 벌어질 것이고, 이는 결국 머지않은 미래에 임금 격차와 빈부격차로 나타날 것이라 필자는 예상한다.


‘대상 독자’를 명확히 파악하고 글쓰기

회사에서 쓰는 글은 본인이 쓰고 싶은 대로 쓰는 게 아니다. 그렇게 글을 쓰고 싶다면 필자처럼 개인 블로그를 하는 쪽을 추천한다. 지금 필자가 블로그에 글을 쓰듯이, 이 글을 누가 읽을지 알 수 없는 상태에서 글을 쓰는 것과는 다르게 대부분 회사 업무에서 글쓰기를 할 때는 그 글을 읽게 될 「독자」가 명확하다. 그리고 그 ‘회사 내의 독자’들은 대부분 본인의 업무와 연봉을 결정짓는 의사결정권자들 혹은 본인을 평가하는 사람들인 경우가 상당히 많다.

회사에 입사하기 전 학교에서 배우는 대부분의 글쓰기라는 게 에세이, 논술, 특정 주제에 대한 글짓기 정도에 한정되다 보니 특정 독자, 아니 정확히 표현해서 ‘보고 받을 사람’을 명확히 하고 글쓰기 하는 연습이 되어 있지 않은 상태에서 사회에 첫걸음을 하게 되는 경우가 대다수다. 그래서 이전 방식의 글쓰기 버릇을 쉽게 버리지 못하는 상태에서 발생하는 실수들이 많이 보인다. 다시 한번 강조하건대, 회사에서 글쓰기를 하는 경우 그 글을 읽는 사람, 혹은 독자를 명확히 파악하는 게 중요하다. 대부분 당신을 평가하는 사람들일 것이므로.

어떤 문서를 작성하든 독자를 명확히 정하고 글을 쓰는 건 중요하다. 문서를 읽는 사람도 그 사람의 살아온 배경에 따라 쌓여 있는 지식의 종류가 모두 다르기 때문에 글 쓰는 사람이 독자를 상정하고 독자가 읽고 이해할 수 있도록 글을 쓰는 게 좋다.

필자와 (같이 나이가 좀 있는 선배들과) 함께 일하는 사람들이라면 (소량의 혼남과 함께) 첨삭지도를 받을 수 있겠지만, 요새는 다양한 회사에서 다양한 환경에서 일을 하고, 평등함을 강조하고 있으며, 또 그래서 특정 부서가 유닛 형태로 1~2명만 존재하는 경우가 많아 이런 글쓰기를 배우기에 어려움을 이해한다.

회사에서 문서를 만들 때는 문서 서두에 ‘문서 소개’에 해당 문서의 독자가 누구인지 명시하는 게 매우 좋은 방법이다. 본인이 누가 이 문서를 읽을지에 대해 가정했다는 걸 명시하는 게 좋다.

예를 들어, 이런 경우를 상정해 보자. 만약 아래와 같은 상황이 고민이 된다면 어떻게 해야 할까?

  • 문서로 API 연동에 대해 설명해야 한다.
  • 보고를 받을 사람들 중에는 개발 전문가도 있지만, 비-전문가(의사결정권자)들도 있다.

이런 경우 문서는 누구에 맞춰서 써야 할까? 대부분의 개발 문서들은 이런 경우 개발 전문가들이 읽을 것임을 상정하여 쓰인다. 그리고 이런 걸로 고민하는 직원을 대하게 되면 대부분 그냥 “그냥 다 해~” 라고 하곤 한다. “다 해라” 라니. 너무 무책임하게 들릴 수도 있다. 근데 이게 무슨 소리냐면, 이런 상황에서 API 문서를 만들거나, API와 관련한 보고서를 써야 한다면 고민하지 말고 그냥 두 개 모두 쓰고 난 후 목차에서 읽을 사람을 가릴 수 있도록 하거나, 혹은 문서의 서두에 ‘누구누구, 혹은 무슨무슨 역할은 여기저기만 읽으시오’ 하고 소개하면 된다는 이야기다. 문서를 별도로 두 개 이상 만들 이유도 없고, 그럴 필요도 없다. 기술 문서를 만들어야 한다면 API 연동 부분과 API에 대한 배경 설명을 분리해서 작성하면 된다.

또 다른 예로, 꽤 비싼 가격의 소프트웨어 도구를 도입해야 하는 경우라면?

이런 의사결정은 대부분 소프트웨어에 비-전문가들인 경영진들에 의해 결정되게 된다. 소프트웨어의 가치를 명확하게 이해하지 못하는 사람들에게 투자를 요청하는 과정에서의 글쓰기는 당연히 소프트웨어적인 관점 보다는 투자 대비 효율에 대한 관점으로 글쓰기 해야 한다. 큰 비용이지만, 이를 투자함으로 인해 얻어지는 결과를 명확히 설명할 수 있다면, 내부 업무 개선과 영업 이익 개선으로 이어짐을 설득해야 하는 것이다.

그 외에도 회사 대 회사로 Business To Business(B2B) 사업을 하는 업무를 담당하고 있다면, 테크니컬 라이팅(Technical Writing) 역량이 매우 중요한 핵심 기술임을 이해해야 한다. 우리 회사에서는 당연한 것들이 상대 회사에는 당연하지 않을 수 있다는 점을 이해해야 하며, 명료하고 정확한 글쓰기를 할 줄 알아야 한다. (이에 대해서는 테크니컬 라이팅 강의를 듣거나, 도서를 구입하여 공부하시기를 추천한다.)

같은 선상에서 엔지니어 대 개발자로 Engineer To Developer 업무를 수행해야 하는 프로젝트 조직 내에서 기획, 설계, 버그 리포팅 등 내부 인원들이 보는 문서를 작성해야 한다면, 이 또한 내부 인원들의 수준과 용어에 대한 이해, 내부 조직 문화 등 여러 상황을 고려하여 문서를 작성해야 한다.


좋은 보고서 쓰기

좋은 글쓰기 중 사회생활을 하는 우리가 알아야 하는 결정적인 지식은 ‘보고서 작성 방법’과 관련한 내용들이다. 인터넷 검색을 하면 다양한 주제와 많은 전문가가 각기 다른 관점으로 써둔 훌륭한 지식이 있다. 그러므로 필자의 글도 간단히 그 정도로 참고만 해 주시면 좋겠다.

  1. 독자
    • 보고서 작성 시 일한 사람 중심이 아닌 보고서를 읽을 사람(의사결정권자) 중심으로 써야 한다.


  2. 결과의 위치와 성격
    • 보고서는 두괄식으로 작성해야 한다. 보고 결과는 앞쪽에 표시되어야 한다. 결과를 뒤로 숨기지 않도록 한다.
    • 보고 결과의 핵심을 요약해라. 어떻게 일했고, 뭐를 개선해야 하는지는 나중에 따로 정리해도 된다.


  3. 초안
    • 처음부터 완벽하게 쓰려고 하지 말고, 초안을 쓰고 고치는 방식으로 접근해라
    • 초안을 쓰는 동안은 고치지 마라. 고치는 동안 뭘 작성하려 했는지 잊어버린다.
    • 초안은 문서의 전체적인 구조를 잡는 데에만 집중하면서 작성하면 된다.


  4. 본 작성
    • 작성 시 초안을 고치면서 데이터가 정확한지 확인해라.
    • 의사결정에 필요한 내용이라면 첨부해야 할 내용들을 모두 의사결정권자들이 알게 해야 한다.
    • 읽기 쉽게, 읽는 사람이 재미를 느끼게 쓰는게 좋다.


  5. 교정
    • 초안-본 작성 후 교정 시에는 보고서를 쓰고, 고치다 보니 원래 목적했던 독자인 의사결정권자에게 필요하지 않은 내용이 있는지 확인한다.
    • 교정 시에는 서두에 작성한 결과와 다른 데이터가 있는지, 있다면 왜인지 명확히 분석하고 다듬어야 한다.
    • 보고서에는 절대 외국어, 줄임말, 유행어를 함부로 쓰지 마라. 교정 시 이 부분을 모두 명확한 용어로 변경하자.
    • 10년 뒤에 보고서를 읽어도, 무슨 소린지 알 수 있도록 명확하게, 명료하게 작성하라.


  6. 검토
    • 보고하기 전에 주변에 검토해줄 사람을 찾아라. 직장 상사라는 건 그럴 때 쓰라고 있는 거다.
    • 맞춤법 검사기 많으니 제발 검사 좀 해라.
    • 보고서에 존재하는 잦은 오탈자는 보고서 데이터 전체의 신뢰를 망가뜨린다.


  7. 마무리
    • 문서 끝부분에는 결과 보고서와 관련한 참고 자료를 동봉하자. 예를 들어, 버그 리포트라면 버그 목록을 참고 자료로 첨부하는 식이다.
    • 문서 마지막에는 함께 일한 동료들을 모두 언급하자. 함께 일한 우리 모두의 성과임을 잊지 말자. 성과를 독점하는 건 정말 나쁜 짓이다.


3편 끝. 4편에서 계속.


참고 자료