도움말 파일 하나가 1,026줄이 된 사연

지난 글에서 “도움말이 길어졌다”고만 적고 넘어갔습니다. 다시 열어서 세어봤습니다. 1,026줄이었습니다.

버튼이 없으면 전부 말로 설명해야 합니다

화면에 버튼이 있는 프로그램이라면 이럴 일이 없습니다. 버튼이 거기 있는 것 자체가 “이런 기능이 있다”는 안내이기 때문입니다. 누르면 뭐가 되는지 대충 짐작도 됩니다.

텔레그램은 그게 없습니다. 명령어를 아는 사람만 쓸 수 있고, 뭘 칠 수 있는지는 어딘가에 글로 적어놔야 합니다. 그래서 명령어 하나마다 네 칸을 채웠습니다. 무엇을 하는 명령인지, 어떻게 쓰는지, 실제 예시, 그리고 조심할 점.

명령어가 서른 개 넘게 있으니 이 네 칸짜리 블록도 서른 개 넘게 쌓입니다. 이것만으로도 파일이 길어질 이유는 충분했습니다.

명령어는 혼자 다니지 않았습니다

1. 버튼이 없으니 전부 말로 설명해야 한다 명령어 하나마다 기능·사용법·예시·주의사항 네 칸
2. 명령어가 서른 개 넘게 있다 네 칸짜리 블록이 서른 번 넘게 반복된다
3. 명령어가 그룹으로 묶여 있다 하나가 아니라 그룹마다 딸린 하위 명령어 서너 개씩
4. 그룹마다, 하위 명령어마다 또 설명이 필요하다 서른 개가 아니라 서른 곱하기 몇이 됐다

예를 들면 이런 식입니다. 명령어 하나가 그 밑에 추가·삭제·목록·설정 같은 하위 동작을 서너 개씩 거느리고 있었습니다. 그룹 이름 하나만 치면 그 밑에 딸린 하위 명령어를 한꺼번에 보여주는 기능도 따로 만들어야 했습니다. 명령어 개수를 셀 때는 서른 몇 개라고 생각했는데, 실제로 설명해야 하는 건 그 그룹들 안의 하위 명령어까지 다 합친 숫자였습니다.

줄이려고 만든 별칭도 결국 문서가 필요했습니다

명령어 이름이 길어서 매번 치기 귀찮은 것들은 짧은 별칭을 만들어줬습니다. 그런데 별칭을 만들고 나니 새로운 문제가 생겼습니다. 이 별칭이 뭐였는지도 또 외워야 한다는 것이었습니다.

편하려고 줄였는데, 줄인 것 자체가 또 하나의 설명거리가 됐습니다. 결국 “이 별칭은 원래 이 명령어입니다”라는 매핑표도 코드 어딘가에 남아야 했습니다.

그나마 다행이었던 것

다시 열어보고 다행이라고 생각한 부분이 하나 있었습니다. 도움말을 부를 때 1,026줄을 한꺼번에 보여주는 게 아니라, 명령어 이름을 붙여서 물어보면 그 명령어 하나의 설명만 찾아서 보여주는 구조로 만들어뒀다는 것입니다.

전체를 다 보여주는 방식이었다면 아마 진작에 이걸 아무도 안 읽었을 겁니다. 궁금한 것 하나만 찾아볼 수 있게 만들어둔 게, 그때는 별생각 없이 한 선택이었는데 지금 보니 옳은 선택이었습니다.

남은 교훈

1. 버튼 없는 인터페이스는 문서량이 기하급수적으로 늘어납니다. 화면이 안 보여주는 걸 전부 글로 때워야 하기 때문입니다.
2. 평평해 보이는 목록도 실제로는 계층입니다. 명령어를 셀 때는 서른 개였는데, 그 안에 그룹과 하위 명령어가 숨어 있었습니다.
3. 줄이려고 만든 게 또 다른 설명거리가 될 수 있습니다. 별칭은 편의를 위한 것이었는데, 그 편의 자체를 설명하는 문서가 또 필요했습니다.
4. 전부 보여주기보다 필요한 것만 찾아보게 하세요. 1,026줄짜리 문서라도, 한 번에 하나씩만 꺼내 볼 수 있으면 부담이 훨씬 줄어듭니다.

숫자를 정확히 세어보기 전까지는 그냥 “좀 길다” 정도로만 생각했습니다. 1,026이라는 숫자를 직접 보고 나서야, 제가 만든 게 생각보다 훨씬 복잡한 것이었다는 걸 알았습니다.