기본 콘텐츠로 건너뛰기

매뉴얼이 필요없는 소프트웨어를 만들 자신이 없으면 매뉴얼이라도 잘 만들어라.

솔직히 우리가 소프트웨어를 쓰면서 매뉴얼을 보는 경우가 얼마나 있을까?

아무리 기억을 되살려보아도 내가 MS 워드를 쓰면서 MS의 사용자 설명서를 읽었던 기억은 없다.

옆사람을 통해서, 서점의 책을 통해서 알음 알음 배워서 사용을 했지, 사용자 설명서를 읽었던 기억은 없다.

여러곳을 테스트 하러 돌아다니다보면 많은 경우 매뉴얼이 없거나 매우 부실한 경우가 허다하다.

많은 곳에서 사람들이 읽지도 않을 사용자 설명서를 만드는 것은 시간낭비, 돈낭비, 인력낭비라고 생각을 한다.

물론 나도 그렇게 생각한다.

하지만 사용자 설명서가 없을거라면 소프트웨어 자체가 사용하기 편해야 함에도 불구하고 실제로는 그렇지 않은 경우가 많다.

이런 경우 개발자에게 사용자들이 이러 이러한 것은 불편하거나 오해할 소지가 있으니 수정해 달라고 아무리 얘기해봐야 소귀에 경 읽기이다.

왜냐하면 개발자에게는 이미 그렇게 사용하는 것이 완전히 익숙해져서 불편함이 없기 때문이다.

이런 경우 내가 주로 사용하는 방법은 두가지가 있다.

첫번째는 사용자 테스트를 수행해서 실제로 사용자들이 제품을 어떻게 사용하는지 보여주는 것이다.

하지만 이 방법은 돈도 들고 시간도 들고 실제로 실무에서 이뤄지는 경우가 많지 않다.

두번째는 개발자에게 매뉴얼을 작성하게 하는 방법이다.

즉, 엉성하기 짝이 없는 언제 업데이트 되었는지도 알 수 없는 최종 매뉴얼을 가져다 놓고 제품을 사용하도록 하는 것이다.

이때 중요한 것은 매뉴얼에 적힌것만 수행하도록 하는 것이다.

예를 들어 어떤 웹 서비스에 로그인을 하는 기능이라면

많은 경우 사용자 설명서에는 해당 설명이 아예 빠져 있거나(실제로 빠져 있는 경우가 많다. 왜냐하면 많은 개발자들은 사용자가 로그인 기능을 사용하지 못하는 사용자는 없다고 생각하는 경우가 많으며, 실제로 많은 사용자들이 로그인 기능을 사용하지 못하는 경우는 찾기 힘들지만 어떤 경우에는 로그인을 할 수 있는 영역을 사용자가 찾지 못하거나 로그인이 필요없는 경우에도 로그인을 강제하는 경우가 발생하는데 이러한 경우를 찾는데 매뉴얼이 나름 유용하게 사용되는 경우가 있다.) 설명이 극히 부실하다. 예를 들면 이런 식이다.

'ID와 PW를 입력하고 로그인한다.'

여러분은 위의 문구만으로 로그인이 가능하다고 생각되는가?

만약 가능하다고 생각하신다면 이미 로그인에 완전히 익숙해져 있는 경우이다.

실제로는 저보다 조금 더 자세하게 적어야 한다.

예를 들면

1. 올바른 ID와 PW를 입력해야 한다. 당연하다고 생각하는가? 당연하다고 무시하는 순간 사용성은 쭉쭉 떨어지게 되어 있다. 당연한 것은 없다는 생각이 사용성을 높이는 첫걸음이라고 할 수 있다.

2. 올바른 ID와 PW는 사용자가 가입 당시 적은 ID와 PW이다.

위 사항을 반영하면 대충 이런 식으로 적게 된다.

'가입 당시 기입한 ID와 PW를 입력하고 로그인한다.'

이걸로 충분할까?

조금 더 생각을 확장해보면 예외 사항 즉, 실패하는 경우를 추가해주면 더욱 좋다.

즉, 사용자가 ID와 PW를 잊은 경우에 해당하는 행동 절차를 추가해주면 좋다.

많은 사용자 설명서에는 ID와 PW를 잊어버렸을 때 행동 요령이 누락되는 경우가 많다.

그렇다면 최종적으로 이런 문구가 될 것이다.

'가입 당시 기입한 ID와 PW를 입력하고 로그인을 선택하십시오. ID와 PW를 잊으신 경우 ( ) 로 ID를 찾거나 PW를 재설정 하실 수 있습니다.' (PW를 잊어버렸을 때를 사용자 설명서에 추가하는 것은 PW가 기억나지 않을 경우 서비스들마다 대처방안이 틀리기 때문에 사용자들에게 이를 명확히 하기 위함이다. 어떤 업체는 PW를 재발급 해주는 곳이 있는가 하면, 어떤 곳은 문자나 이메일로 PW를 보내주는 곳도 있다.)

이걸로 끝일까?

하나 더 생각해 볼 수 있다.

즉, ID와 PW에 입력 가능한 문자값을 알려주는 것이다. 이것은 가입 양식과 비교하며 테스트할 때 매우 유용한 정보가 된다. 실제로 가입 양식의 ID에 입력 가능한 문자 수와 로그인 입력 필드에 입력 가능한 문자수를 다르게 제한한 경우도 있었다. 지금 생각해도 조금 황당하다.

그러면 마지막으로 완성되는 문구는 이런 문구가 될 것이다.

'가입 당시 기입한 ID와 PW를 입력하고 로그인을 선택하십시오. ID는 영문 대소문자, 숫자로 8자까지 입력 가능하며, PW는 영문 대소문자, 숫자, 특수문자를 포함하여 16자리 까지 입력 가능합니다. 한글은 입력하실 수 없습니다. ID와 PW를 잊으신 경우 ( ) 로 ID를 찾거나 PW를 재설정 하실 수 있습니다.'

이렇게 상세하게 작성된 매뉴얼은 실제 테스트 케이스를 도출하거나 테스트를 수행할 때 테스트 시간을 크게 단축시켜주는 역할을 한다.

그리고 매뉴얼에 적용된 사항이 제품에 반영되어야 하므로 제품이 가져야할 오류 허용성을 높이는 효과도 조금은 볼 수 있다.

얘기는 길어졌지만 내가 하고 싶은 얘기는 이거다.

많은 사람들이 매뉴얼을 만드는 작업을 매우 힘들어하고 귀찮아한다. 사용자들이 매뉴얼을 잘 보지 않는 것도 사실이다. 매뉴얼을 사용자를 위해서 만든다고 생각을 한다면 이것은 사실이다.

하지만 생각을 조금 바꾸어서 매뉴얼을 일기라고 생각을 해보자.

매일 매일 개발되는 기능들에 대해서 일기를 적듯이 매뉴얼을 적는 습관을 가진다면 제품에 대한 이해와 사용자에 대한 이해를 조금은 높일 수도 있다고 생각된다.

매뉴얼이 없는 제품을 만들 수 있다면 그게 제일 좋은 방법인건 확실하다.

하지만 우물가에서 숭늉을 찾는다고 숭늉이 우물에서 나오지는 않는다.

모든 일에는 선후가 있다.

사용자를 이해하지 못하는 상황에서 매뉴얼이 필요없는 제품이 나올리 만무하다.

사용자를 이해하려는 노력을 조금 더 해보도록 하자.

난 그 첫걸음으로 많은 개발자들에게 꼼꼼하게 매뉴얼 작업을 하도록 독려하는 편이다.

내 경험상 많은 개발자들과 같이 꼼꼼하게 매뉴얼 작업을 하면서 많은 개발자들이 자신의 제품에 대하여 더 깊이 이해하는 것을 볼 수 있었다.

이러한 노력이 쌓이고 나면 이후에는 정말 매뉴얼을 만들지 않아도 되는 그런 제품을 개발하는 날이 올거라고 생각한다.

댓글

이 블로그의 인기 게시물

피드백 루프: AI 시대 테스터가 지켜내야 할 핵심 엔진

소프트웨어 개발과 테스팅 현장에서 가장 자주 언급되지만, 막상 시스템이 복잡해질수록 쉽게 경시되곤 하는 핵심 개념이 바로 '피드백 루프(Feedback Loop)'입니다. 코드를 수정하고, 빌드하고, 테스트 결과를 확인하고, 다시 개선하는 그 순환 과정의 속도와 정확도가 결국 소프트웨어의 품질을 결정짓기 때문입니다. 품질 전문가 매슈 하이저(Matthew Heusser)가 자신의 블로그 Quality Remarks에 기고한 "One Loop After Another" 아티클은 바로 이 피드백 루프의 다층적 구조와, AI 시대에 우리가 놓치지 말아야 할 품질 검증의 본질을 날카롭게 되짚어 줍니다. (출처: Quality Remarks - One Loop After Another / Matthew Heusser) https://qualityremarks.com/one-loop-after-another/ 매슈 하이저는 소프트웨어 개발 생태계가 단순히 하나의 커다란 테스트 루프로 돌아가는 것이 아니라, 시간 축과 관점에 따라 겹겹이 쌓인 '연쇄적인 피드백 루프들(One Loop After Another)'로 이루어져 있다고 설명합니다. 초단기 루프 (Inner Loop): 개발자가 코드를 작성하는 몇 초~몇 분 단위의 루프입니다. 단위 테스트(Unit Test)나 IDE의 Linter, AI 자동 완성이 즉각적인 피드백을 주는 영역입니다. 단기 루프 (Daily / CI Loop): 커밋과 푸시가 이루어지고, CI/CD 파이프라인에서 통합 테스트와 정적 분석이 실행되는 몇 시간 단위의 루프입니다. 중기 루프 (Iteration / Exploration Loop): 스프린트 단위로 탐색적 테스팅(Exploratory Testing)을 수행하고, 실제 사용자 시나리오나 엣지 케이스를 사람이 직접 검증하며 시스템의 유기적 작동을 확인하는 며칠~몇 주 단위의 루프입니다. 장기 루프 (Outer / Market Loop): 실제 ...

에이전틱 AI 프로젝트에서 테스터의 5가지 핵심 원칙

AI 코딩 에이전트와 자율형 에이전트가 빠르게 개발 워크플로우에 통합되면서, 단순히 코드를 잘 짜는 것을 넘어 '에이전트와 어떻게 협업하고 통제할 것인가'가 개발자와 아키텍트들의 가장 큰 화두로 떠올랐습니다. 윤석찬 님의 아티클 "AI 에이전트 시대, 개발자는 어떻게 일해야 하는가? – 프론티어 엔지니어링의 10가지 원칙"은 에이전틱 AI 시대에 엔지니어가 마주하는 패러다임 변화와, 실무 현장에서 일하는 방식을 어떻게 재정의해야 하는지 아주 명확한 가이드라인을 제시해 줍니다. (출처: channy.creation.net - 윤석찬 님의 블로그) https://channy.creation.net/blog/1989 비록 대규모 에이전트 오케스트레이션이나 초거대 인프라 시스템을 개인이 직접 구축하고 운용하는 것은 비용적·기술적으로 현실적인 한계가 있습니다. 하지만 개인 프로젝트에서 AI와 바이브 코딩(Vibe Coding)을 활용하며 겪었던 맥락 손실, 환각, 통제 불능의 경험들을 떠올려보면, 이 아티클이 제시하는 10가지 프론티어 엔지니어링 원칙은 소규모 개인 개발 환경에서도 대단히 깊은 공감을 불러일으킵니다. 이 글은 단순히 "AI 도구를 잘 쓰자"는 수준에 머무르지 않습니다. AI 에이전트가 생성해내는 불확실성 속에서 인간 엔지니어가 시스템의 맥락을 주도하고, 오작동을 제어하며, 품질의 키(Steering Wheel)를 쥐기 위한 구조적 사고법을 다룹니다. 그렇다면 프론티어 엔지니어링의 원칙을 바탕으로, 시스템의 신뢰성과 안전성을 검증해야 하는 테스터는 과연 어떤 실무 원칙을 세워나갈 수 있을까요? 윤석찬 님이 제시한 엔지니어링 원칙을 테스팅 관점으로 재해석해 보면, 다음과 같은 5가지 원칙으로 정리할 수 있을 것 같습니다. 1. 결정론적 검증에서 '경계선 및 허용 오차(Boundary)' 테스팅으로 전환하라 에이전트 기반 시스템은 같은 입력을 주어도 매번 다른 추론 경로를 거치는 확률적(Stoc...

결국 테스팅은 어렵다

 AI 코딩 에이전트와 대형 언어 모델(LLM)이 코드를 순식간에 쏟아내고 테스트 스크립트까지 자동으로 만들어주는 시대가 되면서, 일각에서는 "이제 테스팅도 버튼 하나 누르면 끝나는 쉽고 단순한 일 아닌가?"라는 착각에 빠지곤 합니다. 하지만 품질 전문가 매슈 하이저(Matthew Heusser)가 자신의 블로그 Quality Remarks에 기고한 "Turns Out Testing is Hard" 아티클은, 기술이 아무리 화려하게 발전하더라도 소프트웨어의 '진짜 품질'을 검증하는 일은 여전히 지독하게 어렵고 복잡하다는 현실을 서늘하게 되짚어 줍니다. (출처: Quality Remarks - Turns Out Testing is Hard / Matthew Heusser) https://qualityremarks.com/turns-out-testing-is-hard/ 이 아티클이 말하는 핵심은 간단합니다. 단순한 스크립트 실행이나 표면적인 기능 작동 여부를 확인하는 '체크(Checking)'는 AI나 도구를 통해 얼마든지 자동화하고 속도를 높일 수 있지만, 시스템의 숨겨진 리스크를 탐색하고 비판적으로 질문을 던지는 '진짜 테스팅(Testing)'의 난이도는 오히려 이전보다 더 올라갔다는 점입니다. AI 코딩 에이전트가 단 몇 초 만에 수백 줄의 코드를 생성을 해내면서 당장 눈앞의 기능은 돌아가는 것처럼 보입니다. 하지만 그 이면에서는 오작동이 일어날 수 있는 엣지 케이스, 시스템 간의 미묘한 맥락 단절, 그리고 나중에 거대한 장애로 돌아올 인지부채가 순식간에 쌓여갑니다. 매슈 하이저는 왜 테스팅이 여전히 지독히 어려운 과제로 남아있는지 몇 가지 근본적인 이유를 제시합니다. 첫째, '모호함과의 싸움'입니다. 소프트웨어 요구사항은 언제나 비어있는 행간과 모호함을 품고 있습니다. AI는 주어진 텍스트 그대로 명시적인 조건만 테스트하지만, 실제 인간 테스터는 명시되지 않은 사용...