[TW] Troubleshooting 가이드 톺아보기

시작하며

안녕하세요. 카카오엔터프라이즈 테크니컬라이팅 팀의 Crystal(김유리), Sandy(차신영), Rayna(홍성빈)입니다.

얼마 전 개발자 한 분이 다급하게 찾아오셔서 저희에게 도움을 요청하신 적이 있습니다. 사정을 들어보니 최근 여러 고객사에서 "404 오류가 났는데 어떻게 해야 하나요?", "Access unavailable 오류 났어요!", "오류 코드 정리된 게 있나요?" 등의 문의에 답변을 하다 보니 정작 본인의 개발 일정에 차질이 생겼다는 것이었는데요. 특정 문의에 동일한 답변을 계속해야 할 뿐만 아니라 동일한 내용에 대해 두 명의 개발자가 각각 문서를 작성하는 일도 생겼다고 합니다. 이럴 때 오류 상황과 해결 방법을 모아 정리해둔 문서가 있었다면 CS를 처리하는 리소스를 훨씬 줄일 수 있었을 것입니다. 이런 상황에 효과적으로 대처할 수 있는 문서가 바로 Troubleshooting 가이드입니다.

Troubleshooting이란 문제가 발생한 원인을 규명하고 이를 복구할 때까지의 작업을 말합니다. 개발 중 발생할 수 있는 여러 문제들과 이에 대한 해결 방법을 정리한 것이 바로 Troubleshooting 가이드라고 할 수 있습니다. Troubleshooting 가이드는 내/외부 개발자 모두에게 중요한 문서인데요. 특정 서비스를 개발한 내부 개발자 입장에서는 반복적인 문의에 대한 해결과 효율적인 리소스 운영에 큰 도움을 주고, 외부 개발자 입장에서도 개발 중 발생한 문제에 대한 해결책을 편리하게 찾아볼 수 있다면 훨씬 빠르게 문제를 해결할 수 있기 때문입니다.

오늘날에는 많은 IT 기업들도 기술문서와 함께 Troubleshooting 가이드를 제공하고 있습니다. 오늘은 릴리즈 노트 톺아보기, API 문서 톺아보기에 이어 톺아보기 시리즈 세 번째로 Troubleshooting 가이드를 톺아보겠습니다.

Troubleshooting 가이드 구성 요소

일반적으로 Troubleshooting 가이드는 오류 상황을 나타내는 오류 코드 혹은 오류 메시지, 문제 원인 및 증상, 해결책으로 구성됩니다. 각각의 구성 요소를 나타내는 세부 방법은 회사별로 조금씩 다를 수 있지만, 대부분 구성 요소는 비슷합니다. 그렇다면 좀 더 구체적으로, IT 분야의 Troubleshooting 가이드의 구성 요소와 이런 구성 요소들이 문제 해결 과정에서 어떤 의미를 갖는지 알아보도록 하겠습니다.

① 오류 코드

오류 코드는 Troubleshooting 가이드의 대표적인 구성 요소 중 하나로, 오류 발생 상황을 세 자리 숫자 코드로 정리한 것입니다. 일반적으로 오류 코드는 400, 401과 같은 HTTP 상태코드로 표기합니다. HTTP 상태코드의 첫 번째 숫자는 응답의 클래스를 정의합니다. 하지만 HTTP 상태코드가 아닌 다른 방식으로도 오류 코드가 존재할 수도 있는데요. 예를 들어 400번 대나 500번 대에 해당하지 않는 오류가 발생했다면, 상황에 맞게 KIE001와 같은 고유한 오류 코드를 새로 정의하기도 합니다.

분류	설명
1xx (정보)	요청을 받았으며 프로세스를 계속 진행
2xx (성공)	요청을 성공적으로 받았으며 인식했고 수용함
3xx (리다이렉션)	요청 완료를 위해 추가 작업 조치가 필요
4xx (클라이언트 오류)	요청의 문법이 잘못되었거나 요청을 처리할 수 없음
5xx (서버 오류)	서버가 명백히 유효한 요청에 대해 충족을 실패

[표1] HTTP 상태코드

② 오류 메시지

상황에 따라 오류 코드와 함께 문장 형식으로 오류를 정의하기도 하며, 이를 오류 메시지라고 합니다. 오류 메시지는 해당 오류를 쉽고 빠르게 이해하고 해결하는 데 목적이 있으므로, 최대한 쉽고 간결하게 쓰는 것이 좋습니다. 이때 중요한 점은 오류 메시지를 읽는 독자가 개발자, 운영 담당자, IT 부서 직원, 최종 사용자 등이 될 수 있다고 가정하고 오류에 대응할 수 있도록 메시지를 작성해야 한다는 것인데요. 또한 개발자들은 오류 메시지를 그대로 복사하여 검색하려는 경향이 있기 때문에, Troubleshooting 가이드에서도 화면에 표시되는 오류 메시지를 그대로 인용하는 것이 좋습니다.

③ 원인/증상

문제를 해결하기 전에 문제 원인이나 증상을 명확하게 파악하는 것 또한 문제 해결만큼이나 중요한 항목입니다. 따라서 Troubleshooting 가이드에 오류 코드나 오류 메시지 뿐만 아니라 독자에게 명확한 문제 상황을 안내하는 것이 더 근본적인 문제 해결에 도움이 될 것입니다. 또한 개발 환경 등에 따라 동일 오류가 다른 증상으로 나타날 수도 있기 때문에, 해당 증상들을 정확하게 문서화 하는 작업도 필요합니다.

④ 해결책

Troubleshooting 가이드의 최종 목적은 결국 문제 상황의 해결이므로, 해결책 부분이 가장 중요한 항목이라고도 볼 수 있는데요. 가장 중요한 항목인 만큼 해결 방안을 정확하고 명확하게 안내하여 독자가 문제를 해결할 수 있도록 도와야 합니다. 넘버링 등으로 사용자가 취해야 하는 액션을 안내하거나 실제 코드를 제시하는 것도 좋은 방법입니다. 또한 독자가 다시 작업해야 하는 부분이 있다면 관련 문서에 링크를 연결하는 방법도 생각해 볼 수 있습니다.

Troubleshooting 가이드 작성 Tip

Troubleshooting 가이드를 작성할 때 위에서 설명한 구성 요소들을 작성하되, 독자들이 더 유용하게 가이드를 활용할 수 있는 장치를 마련하면 좋습니다. 그럼 Troubleshooting 가이드에서 활용할 수 있는 몇 가지 방법들을 소개해 드리겠습니다.

① 정확한 원인을 파악하도록 도와라

아마 오류 상황을 마주한 개발자가 가장 궁금한 것은 해당 오류가 왜 발생했는지 그 원인일 것입니다. 실제로 똑같은 증상임에도 상황과 환경에 따라 그 원인이 달라지기도 합니다. 원인이 다르면 당연히 해결 방법도 달라지기 때문에 독자로 하여금 문제의 원인을 정확하게 파악하도록 돕는 것이 중요합니다. 이를 위해 문제에 대한 다양한 상황을 제공하여 독자가 본인의 상황에 해당하는 부분을 따라가도록 유도합니다. 또한 진단 테스트 방법 등을 안내하여 여러 가지 경우를 테스트하여 오류의 원인을 더 명확하게 파악하도록 할 수도 있습니다.

② 다양한 케이스를 제공하라

개발 중 발생하는 오류는 정말 다양한데요. 증상이 같지만 원인이 다른 경우도 있고 같은 오류 메시지가 나타난 경우라도 서비스에 따라 그 해결 방법이 다르기도 합니다. Troubleshooting 가이드에는 가능한 이런 경우들을 최대한 고려하여 문서화 하는 것이 중요합니다. 처음부터 모든 오류 케이스들을 제시하는 것이 어려울 수 있지만, 오류 관련 CS가 들어올 때마다 지속적인 문서화와 업데이트를 통해 보다 풍부한 Troubleshooting 가이드를 작성할 수 있습니다.

③ 링크를 활용하라

Troubleshooting 가이드는 다른 가이드와는 달리 처음부터 끝까지 읽을 필요가 없습니다. 본인이 마주한 특정한 오류에 대한 정보를 빠르게 찾는 것이 중요합니다. 가이드 내에 링크 연결을 활용하면 독자가 필요한 정보를 빠르게 찾을 수 있도록 도울 수 있습니다. 가이드 상단에 테이블 혹은 목차 형태로 링크 연결을 제공하면 원하는 부분으로 바로 이동할 수 있어 편리합니다. 또한 어떤 작업을 다시 해야 한다면, Troubleshooting 가이드에 모든 시퀀스를 적기보다는 해당하는 문서로 이동하여 작업을 수행할 수 있도록 링크 연결로 안내하는 것 역시 좋은 방법입니다.

④ 잘 보이는 곳에 위치시켜라

개발 중 오류가 발생했는데 'Troubleshooting 가이드가 어디 있지?' 하고 기술문서 사이트를 이리저리 살펴본 경험이 있으신가요? 일부 문서 사이트에서는 Troubleshooting 가이드가 잘 보이지 않는 곳에 있어서 독자들이 Troubleshooting 가이드를 신속히 찾을 수 없는 상황이 발생하는데요. 시급히 오류 상황을 해결해야 하는 개발자 입장에서 이렇게 Troubleshooting 가이드가 안 보이는 곳에 숨어 있다면 여간 불편하지 않을 수 없습니다. 따라서 Troubleshooting 가이드를 잘 보이는 곳에 위치시키고, 또한 본문 중간에 Troubleshooting 가이드에 대한 링크를 안내 메시지 등으로 제공하는 것도 하나의 팁이 될 수 있을 것입니다.

마치며

이번 포스팅에서는 Troubleshooting 방법론과 구성 요소, 작성 Tip에 대해 자세히 알아보았습니다.

미국 사진 공유 사이트 Flickr의 운영 관리자인 John Allspaw는 이런 말을 했습니다.

Ways in which things go right are special cases of the ways in which things go wrong.

일이 잘 풀리는 것은 일이 잘못되는 경우 중에서 아주 특별한 경우이다.

어쩌면 시스템이 제대로 작동하지 않는 것이 제대로 작동하는 것보다 더 흔한 일이라고 여겨지기도 하는 것 같습니다. 개발자라면 공감하실 테지만, 실제로 개발 과정에서 하루에도 수십 번 오류 코드에 직면하는 일이 발생합니다. 오류에 직면했을 때, 대부분 개발자들은 가장 먼저 해당 서비스의 기술문서 사이트에 접속하여 해당 오류 코드를 검색하게 됩니다. 'Command + F' 아니면‘Ctrl + F’ 키를 사용하든, 또는 사이트 검색 기능을 사용하든 이들의 목적은 눈앞에 보이는 오류 코드에 대한 정보를 찾는 것일 텐데요. 이들을 실망시키지 않기 위해 테크니컬라이터들도 문서에 누락된 오류 코드나 오류 메시지는 없는지 면밀하게 살펴보아야 할 것입니다. 또한 경험적에 비춰보면 개발자들이 문서 초안을 작성할 때 Troubleshooting 내용은 누락시키는 경우가 많기 때문에, 문서 기획 단계에서부터 개발자들에게 Troubleshooting 가이드의 중요성을 인식시키고 함께 가이드의 구성을 고민해 볼 것을 제안하는 바입니다.

어느덧 톺아보기 세 번째 아티클을 소개해 드리게 되었네요. 독자들의 테크니컬 라이팅에 대한 중요성 인지와 스킬업에 대한 나름의 당찬 목표를 가지고, 곧 다음 아티클도 준비해서 돌아올게요 :) 감사합니다.