DLP 관리자 매뉴얼을 받았는데 스물다섯 쪽이고 화면 캡처와 설명이 짝지어진 구성이었다. 첫 세 쪽만 달랐는데 기능이 아니라 조회와 등록과 수정의 공통 동작을 규정하고 있었다.
Table of contents
Open Table of contents
앞 세 쪽의 공통 규정
조회하면 상세가 오른쪽 divDetail 에 뜬다는 것과, 초기 상태에서는 btnSave 가 비활성이라는 것이 적혀 있었다. 등록에서 필수 항목이 비면 MSG_REQUIRED 문구가 어디에 뜨고, 결과를 divMessage 에 알린다는 것도 있었다.
나머지 스물두 쪽은 그 동작을 전제로 각 기능만 설명한다. 같은 문장을 반복하지 않아도 되는 구성이었다.
스무 번 쓰면 그중 몇 개가 달라진다
이 규정이 없으면 기능마다 같은 설명을 반복해야 하고 매뉴얼이 두꺼워진다. 그런데 더 나쁜 것은 반복 자체가 아니었다.
같은 동작을 스무 번 쓰면 그중 몇 개는 표현이 달라지고 읽는 사람은 실제로 다른 동작이라고 읽는다. divMessage 가 어떤 쪽에서는 「알림 영역」, 어떤 쪽에서는 「결과 창」이 되는 식이다. 앞에서 한 번 규정하면 그 어긋남이 생길 자리가 없어지고 그 규정은 개발자에게 명세가 된다.
판단 기준까지 적힌 자리
한 줄이 특히 눈에 띄었는데 데이터 중요도 grade 를 보고 btnDelete 의 visible 을 제한한다는 문장이었다. 어느 화면에 있고 없다가 아니라 무엇을 보고 정하는지가 적혀 있었다.
그러면 새 화면을 만들 때 물어보지 않고 그 기준으로 정할 수 있다. 앞서 본 다른 문서는 삭제 경로가 리소스마다 있고 없는데 그 기준이 어디에도 없었다.
색과 문구와 같은 자리
오류 표시를 색과 문구 둘 다 주게 규정한 것도 좋았다. is-invalid 테두리는 여기가 문제라는 것만 말하고 MSG_REQUIRED 같은 문구가 왜 문제인지를 말한다.
성공과 실패를 같은 divMessage 에 표시하게 한 것도 이유가 있다. 자리가 다르면 성공에 익숙해진 사람이 실패가 뜨는 자리를 안 보게 되고 실패했는데 성공한 줄 안다.
캡처와 규정의 수명
이 매뉴얼의 약점은 스물두 쪽이 화면 캡처라는 점이었다. 버튼 위치 하나만 옮겨도 그만큼이 낡는다.
캡처 안에 관리자 템플릿의 기본 공지가 몇 해 전 날짜로 남아 있는 것도 그대로 실려 있었다. 이것을 고치는 데는 두 가지 방법이 있었다. 캡처 스물두 쪽을 지금 화면으로 다시 찍는 것과, 캡처는 그대로 두고 찍은 날짜를 함께 넣는 것이다. 뒤쪽을 골랐다. 이유는 다시 찍은 캡처도 다음 개편에 또 낡아서다. 공통 동작 규정은 화면 개편을 해도 대개 유지되므로 캡처보다 오래 산다. 그래서 규정은 앞에 두고 캡처는 뒤에 두며 찍은 날짜를 함께 남기는 편이 낫다.
정리
- 공통 동작을 문서 앞에 한 번 규정하면 반복이 사라진다
- 반복 과정에서 생기는 표현의 어긋남도 함께 사라진다
- 그 규정은 사용자에게 매뉴얼이고 개발자에게 명세다
divDetail·btnSave·divMessage같은 자리 이름이 규정과 기능 설명을 잇는다- 기능 설명뿐 아니라 판단 기준을 적으면 새 화면에서 안 물어도 된다
- 오류 표시는
is-invalid색과MSG_REQUIRED문구를 둘 다 준다 - 성공과 실패를 같은
divMessage에 표시한다 - 화면 캡처는 빨리 낡고 동작 규정은 덜 낡는다
- 캡처에는 찍은 날짜를 넣어 낡았는지 판단할 수 있게 한다