이전 편에서는 필자가 경험치로 쌓아온 버그 보고 시 지켜야 할 사항들과 주의해야 할 사항들에 관해 설명했다면, 이번 편에서는 필자가 실제로 보며 첨삭했던 문장들과 그런 글들에서 느낀 뉘앙스에 대한 이야기를 해 볼까 한다. 혹은 ‘정확히 규칙이랄 건 없지만 알고 작성하면 세련되어 보이는 버그 보고 노하우’ 정도의 팁(tip)들이다. 필자가 이전 편들에서도 언급하였지만, 버그 보고는 Technical Writing의 일종이다. 그러므로, 전문성을 가지고 작성해야 한다.
필자는 기본기를 굉장히 중시하는 성향이다. 그러니 이 글에 검색해서 들어오신 분이시라면 본 포스팅의 내용에 앞서 꼭 1편, 2편, 3편, 4편, 5편을 먼저 읽어보시기를 추천드린다.
실전 좋은 문장, 실전 나쁜 문장, 그리고 약간의 설명
문단 나누기나 단어/용어 선택을 잘해서 기술 문서를 작성하는 건 글쓰기 연습을 하는 개인의 의지 문제이므로, 그 부분은 그 부분대로 두고, 조심해야 할 뉘앙스나 쓰지 않아야 할 표현들에 대해 실제 사례들을 짚어보려 한다.
실사례1)
…됩니다, 됩니다, 됩니다. 수동태 : 그 마법을 써야 할 경우와 쓰지 말아야 할 경우.
• “홍길동은 도술을 써서 부자의 창고를 또다시 털었습니다.”는 능동태다. “또다시 홍길동입니다. 창고가 도술에 의해 털렸습니다.”는 수동태다. 글쓰기 연습을 좀 심각하게 했던 사람이라면 차이를 바로 알 수 있는데, 그 차이의 근본적은 바로 ‘주어’가 명시되었느냐, 암시되거나 감추어졌느냐에 대한 차이다.
• 수동태를 사용하면 행위의 주체가 감추어지는 마법이 발생한다. 버그 보고 시에는 사실 이 수동태 형태의 문장을 전술적으로 많이 사용해야 한다. 소프트웨어에 대한 이해가 적은 사람들은 버그가 프로그래머의 역량 부족에 의해 발생한다는 오해를 하는 경우도 있기 때문에 ‘누가 개발했다’라는 정보를 의도적으로 숨기기 위해 사용하는게 좋다. 혹은 누가 개발했는지에 대한 정보가 명확하더라도 (이전 편에서 필자가 ‘지적하지 마라’라고 언급한 바와 같이) 나타나는 문제에 대한 잘잘못을 따지지 않기 위해서 사용한다.
• 버그 보고 시에는 수동태를 써야 한다고 설명하였지만, 모든 문장을 수동태로 쓰지 말자. 버그 보고에서 수동태를 써야 하는 이유는 위에서 설명했지만, 모든 문장이 수동태면 현상을 명확하게 명시할 수 없다. 버그가 발생하는 현상에 다다르기 위한 사용자 혹은 시스템의 행위에 대해 주어를 명시해야 한다. 그래야 내용이 명확해진다.
• 그리고, 특히 테스트 결과 보고서 같은 보고서류를 쓰다 보면 “준비됩니다”, “사용됩니다”, “처리하게 되었습니다” 등으로 “… 됩니다, 됩니다, 됩니다”라는 표현을 많이 사용하게 된다. 가능한 좋은 내용들은 능동적으로 누가 행위를 하였는지 나타내는 게 좋다.
• 수동태와 능동태를 적시적소에만 사용할 수 있어도 다양한 방식으로 의사소통하며 평화롭게 전달해야하는 필요 정보들을 공유할 수 있게 된다.
실사례2)
제목 : 버그입니다.
• 모든 보고서의 제목을 “보고입니다.”라고 보고하는 경우도 종종 있다. 업계로 진입하는 초심자분들 중 이 글을 읽으신 분들이시라면 이제 더 이상 같은 실수는 하지 않으시길 바라며…
• 모든 버그 보고서는 제목에 내용이 요약되어 제목만 보고도 내용을 유추할 수 있도록 해야 한다. 이렇게 말하면 때로 “그럼 제목과 내용이 같아지는데요?”라고 되묻는 경우가 있는데, 그래도 된다. 버그 보고를 하다 보면 정말로 제목과 내용이 똑같을 수도 있는데, 그게 영~ 어색하다면 스크린샷이나 동영상을 하나 준비하면 되지 않을까?
• 내용을 요약해서 제목에 작성해야 하는 이유는 검색했을 때 “버그입니다”만 100개씩 나오지 않도록 하기 위해서다. 같은 UI에서 나오는 버그라고 해도 “특수기호 작성 시 OO가 안되는 버그”, “□ □를 한 후 ○ ○ 사용 시 △△로 보이는 현상”과 같은 방식으로 제목에서 내용을 유추할 수 있어야 오랜 시간이 지난 후 검색해도 쉽게 필요한 내용을 찾을 수 있다.
실사례3)
독자(글 읽는 사람)의 상태를 가정하지 않는게 좋다.
• 다음 문장은 무엇이 문제인지 고민해보자. “말씀드린 내용으로 문제가 재현되지 않는다면 회신하여 주시고, 그 동안 다른 기능들을 먼저 구현하고 계십시오. “ 이 문장은 글을 쓴 사람과 읽는 사람이 상호 신뢰가 확고하다면 크게 문제되지 않을 수도 있다.
• 위 문장의 근본적인 문제는 “내가 준 답은 반드시 맞을 거다”라고 상대의 이해를 강요하는 부분이다. 버그를 보고한다는 행위는 제품/서비스 내에서 뭔가 문제나 현상이 있을 때 이에 대한 정보를 전달하는 것이므로, 과연 보고자(글쓴이)는 문제라고 생각하는 해당 상태에 대해 정확히 파악한 것인가를 먼저 돌아보아야 한다. 그 부분에 대한 확신이 있어야만, 다른 사람에게 “내 말이 맞으니 해 보고 안 되면 알려줘라”라고 말할 수 있는 것이다.
• 어떤 경우에도 다른 사람을 평가하거나, 다른 사람의 이해/감정을 함부로 강요하는 건 나쁜 행동이다. 내가 상대가 하는 말을 이해못할 수 있듯이, 상대도 내가 하는 말을 못알아듣거나 이해하지 못할 수 있다.
• 대부분 이런 식의 문장은 자신이 보유한 지식에 대해 확신이 너무 강한 경우에 나타난다. 자신이 가진 지식에 대한 확신이 너무 강하다는 의미는 사실 아는 게 별로 없다는 소리거나, 원래 남과 타협을 잘 안 하는 사람이라는 의미일 거다. 그런 사람이 되지 말자.
• 첫 번째 예로 든 문장을 꼭 써야 하는 상황이라면, 필자는 좋은 예로 다음의 표현을 추천한다. “혹시 설명이 미흡하여 추가 설명이 필요하시거나, 이해가 어려운 부분이 있으시면 다시 설명 드리겠습니다. 댓글에 요청해 주십시오.”
실사례4)
“…한 문제가 있습니다” 보다는 “…한 현상이 발생합니다”가 훨씬 듣기 좋다.
• 문제를 보고하다 보면 평상시 (일반적인/보통의/소프트웨어 업에 종사하지 않는) 다른 사람들은 부정적인 단어로 인식하거나, 부정적인 문장으로 인식하는 표현을 자주 사용하게 된다. 그렇다 보니, 그 자체가 직업병이 되어 너무 스스로 익숙해지기도 한다. 그래서 「문제, 이슈, 안 됩니다, 오작동합니다」같은 부정적인 표현들을 사용하면서, 그 표현이 어느 정도로 부정적인 인상을 주는지 인지하지 못한 상태에서 자주 사용하곤 한다.
• 이전 편에서 필자는 버그 보고 시 단어와 용어는 해당 회사의 업무 의사소통 시 실제로 사용하는 용어들을 사용하라고 설명하였다. 그렇지만, 버그 보고 시에는 업무에서 잠시 빠져올 수 있어야 한다. 또한, 본인의 직업병 때문에 당연하다고 생각하고 있는 상식들에서 잠시 빠져나와 주변의 평상 표현들을 이용해 버그 보고를 작성하는게 좋다.
• 전편에서 필자가 언급하였지만, 버그 보고 시에는 가능한 긍정적인 표현들로 문장을 만드는 게 좋다. 그러니 「문제, 이슈, 안 됩니다, 오작동합니다」보다는 「… 현상이 발생합니다.」 혹은 기대 결과와 현재 결과를 비교하여 「AA처럼 되어야 하지만, 실제로는 BB라고 발생하고 있습니다.」라는 식으로 가능한 부정적인 표현을 제거하고, 긍정적인 표현으로 교체하여 문장을 만드는게 좋다.
• QA나 Tester의 역할을 잘 이해하지 못하고 “애자일에는 QA 필요 없어요”라는 말을 하는 프로그래머들은 부정적인 표현의 버그 보고를 받게 되면 QA 담당자나 Tester들을 ‘정치하는 사람’ 정도로 인식하는 경우도 종종 있다. 그러니, 본인 업이 오해받지 않도록 하기 위해서는 상대를 존중하고, 긍정적인 글쓰기 하는 역량을 키워야 한다. 이 부분 역시 학습이 필요하다.
실사례5)
무지성(無知性) 짜집기는 너무 성의 없어 보이며, 때론 능력 부족으로 보인다.
• 구글 없이 코딩할 수 있는 프로그래머가 몇 명이나 될까? 2022년 기준, (고인물이 된) 몇몇 Senior 프로그래머들 외에는 아마 거의 없을 거다. 아니, 어쩌면 Senior 프로그래머들도 구글 없이 프로젝트를 끝내기는 어려울 수 있다. 구글은 이미 프로그래머들에게도, 그 외 직군에서 소프트웨어 업에 종사하는 엔지니어들에게도 없어선 안 될 필수 업무 도구가 되어있다.
• 그런데 간혹 구글에서 검색한 결과를 그대로 복사 붙여넣기 하여 보고서에 넣는 경우가 있다. 그리고선 마치 그 글을 자신이 작성한 거처럼 (아무런 참고 링크도 없이) 보고하는 경우가 있는데, 자~ 확실시하자. 표절은 나쁜 거다. 표절하지 말자. 남의 글을 그대로 복사해 왔다면 적어도 그게 무슨 뜻인지 다시 한번 생각하고, 문맥에 맞게 수정해서 사용하자.
• 가장 좋은 것은 남의 글을 가져와 자신의 표현으로 바꾸고, 자신의 용어로 변경하고, 자신의 글에 잘 맞게 녹여 넣는 것이다. 전문가들이 작성한 글을 그대로 가져와 생각 없이 복사-붙여넣기하여 사용하지 말고, 꼭 자신이 한 번 꼭꼭 씹고 소화시켜야 함을 잊지 말자.
• 최소한 버그 보고를 작성할 때 남의 자료를 가져다 써야 한다면 참고 자료는 링크 형태로 제공하고, 특정 구문/표현을 인용해야 할 경우에도 어디에서 인용했는지 가급적 밝혀두는 게 좋다. (특히 버그 보고가 아닌, 사용자 매뉴얼이나 사용자에게 답변이 나가야 하는 경우의 글쓰기라면 더욱 이 부분에 대해 주의해야 한다.)
실사례6)
‘기존’과 ‘신규’의 함정에 빠지지 말자.
• “기존 시스템의 문제점들 때문에…” 라는 말을 보고서에 자주 쓰게 되는데, 이렇게 사용하는 “기존”이라는 단어는 사실 ‘내가 무슨 이야기 하는지 너도 알지?’ 라는 의미를 내포하고 있는 단어이다. 상황에 따라 해석이 굉장히 애매할 수 있다. 예를 들어, 3년 전 쓴 버그 보고서에 “기존 시스템”이라고 되어 있고, 명시된 어떤 내용이 없다면 과연 3년 후인 현재 시점에 해당 버그 보고를 해석할 수 있을까? 그러므로 ‘기존’이라는 표현을 쓸 때는 구체적으로 어떤 게 ‘기존’인지 그 기준을 명시하는 게 좋다.
• “신규”도 마찬가지다. 보고서에 당연하다는 듯이 “신규”, “신규 기능”, “신규 시스템”이라는 말을 많이 쓰곤 하는데 이 단어 역시 사용 시점에는 명확하지만 3년 후, 5년 후에는 정체를 알아볼 수 없는 마법의 단어 중 하나다. 일부러 추적이 불가능하게 하려는 의도가 아니라면 사용을 지양하거나, 문서에 해당 표현을 사용하는 게 문화처럼 되어 있다면 어떤 시스템인지, 어떤 기능인지에 대해 그 ‘신규’를 명시하는 게 좋다.
오늘은 여기까지. 실무를 하다가 또 재미있는 에피소드들이 생기면 내용을 추가할 예정이다. (아닐 수도 있고.)
끝.