매뉴얼 앞에 공통 동작을 규정하면

관리자 매뉴얼을 받았는데 스물다섯 쪽이고 화면 캡처와 설명이 짝지어진 구성이었다. 첫 세 쪽만 달랐는데 기능이 아니라 조회와 등록과 수정의 공통 동작을 규정하고 있었다.

Open Table of contents

앞 세 쪽의 공통 규정

조회하면 어디에 상세가 뜨는지와 초기 상태의 버튼이 무엇인지가 적혀 있었다. 등록에서 필수 항목이 비면 어떻게 표시되고 결과를 어디에 알리는지도 있었다.

나머지 스물두 쪽은 그 동작을 전제로 각 기능만 설명한다. 같은 문장을 반복하지 않아도 되는 구성이었다.

이 규정이 없으면 기능마다 같은 설명을 반복해야 하고 매뉴얼이 두꺼워진다. 그런데 더 나쁜 것은 반복 자체가 아니었다.

같은 동작을 스무 번 쓰면 그중 몇 개는 표현이 달라지고 읽는 사람은 실제로 다른 동작이라고 읽는다. 앞에서 한 번 규정하면 그 어긋남이 생길 자리가 없어지고 그 규정은 개발자에게 명세가 된다.

한 줄이 특히 눈에 띄었는데 데이터 중요도를 판단해 삭제 버튼 노출을 제한한다는 문장이었다. 어느 화면에 있고 없다가 아니라 무엇을 보고 정하는지가 적혀 있었다.

그러면 새 화면을 만들 때 물어보지 않고 그 기준으로 정할 수 있다. 앞서 본 다른 문서는 삭제 경로가 리소스마다 있고 없는데 그 기준이 어디에도 없었다.

오류 표시를 색과 문구 둘 다 주게 규정한 것도 좋았다. 테두리는 여기가 문제라는 것만 말하고 문구가 왜 문제인지를 말한다.

성공과 실패를 같은 자리에 표시하게 한 것도 이유가 있다. 자리가 다르면 성공에 익숙해진 사람이 실패가 뜨는 자리를 안 보게 되고 실패했는데 성공한 줄 안다.

이 매뉴얼의 약점은 스물두 쪽이 화면 캡처라는 점이었다. 버튼 위치 하나만 옮겨도 그만큼이 낡는다.

캡처 안에 상용 템플릿의 기본 공지가 몇 해 전 날짜로 남아 있는 것도 그대로 실려 있었다. 공통 동작 규정은 화면 개편을 해도 대개 유지되므로 캡처보다 오래 사는데 그래서 규정은 앞에 두고 캡처는 뒤에 두며 찍은 날짜를 함께 남기는 편이 낫다.