70 · 문서화 — 사용자

0. 사용자는 누구인가 — 이 저장소에서

자기 회사 자료가 어디에 무엇이 있는지 알고 싶은 사람. CCTV·영상저장장치 자료 12,963 건(2.2 GB) 을 가진 사람이고, 프로그래머가 아닐 수 있다. 장비 SDK 문서·구성도·2013~2014 작업 기록을 다루며, 그 중 388 건의 글이 cp949 로 깨져 있다.

★★ 그래서 사용자 문서의 첫 문장은 「설치」가 아니라 **「무엇을 할 수 있나」**여야 한다.

1. 사용자 문서가 답해야 하는 일곱 물음

# 물음 어디를 가리키나
1 이 도구가 무엇을 해 주나 대장·찾기·3D 공간·계보(11·06)
2 내 자료를 바꾸나 아니다. 대장은 원본 위의 층이다
3 내 자료가 밖으로 나가나 기본은 안 나간다. 협의체를 켤 때만, 그리고 무엇이 나가는지 화면이 보여 준다(13 §5)
4 왜 어떤 파일은 글이 안 보이나 「없다 / 못 뽑았다」의 차이(11 §3)
5 찾기 결과를 믿어도 되나 몇까지 봤는지·뜻 검색이 켜졌는지 화면이 말한다
6 모델이 답을 지어내지 않나 근거를 붙이고, 자료에 없으면 없다고 한다(08 §5)
7 실수하면 되돌릴 수 있나 고침·승격·발현 전부 되돌림이 있다

★★★ 2·3 번이 가장 먼저 와야 한다. 회사 자료를 다루는 도구에서 사람이 가장 먼저 묻는 것이고, 답이 흐리면 아무도 쓰지 않는다.

2. 문장 규약

규약 예
없는 것은 없다고 「뜻 검색은 지금 꺼져 있습니다」 — 「지원 예정」이라고 쓰지 않는다
수를 함께 「문서 202 · 그림 179 · 못 뽑은 것 5」
전문 낱말은 한 번 풀어 쓴다 「genome(자료 한 벌)」
위험한 일은 먼저 말한다 「원격 걷이는 상대 기계에 접속합니다」
명령은 그대로 복사되게 줄바꿈·따옴표까지 정확히

★★ 화면이 말하는 것과 문서가 말하는 것이 같아야 한다. 다르면 사람은 둘 다 안 믿는다 — 검사가 문서의 명령을 실제로 돌려 본다(40 §7 9번 칸).

3. 첫 다섯 분 — 사용자가 처음 하는 일

1. dnarna doctor          이 기계에 무엇이 있는지 본다
2. dnarna catalog scan    자료를 훑는다 (원본은 바뀌지 않는다)
3. dnarna catalog stats   갈래별 수 · 글 상태 셋 · 못 본 것
4. dnarna catalog search --ask "..."   찾는다
5. dnarna space put ...   3D 공간에 놓아 본다

★ 다섯 단계 어디서도 인프라가 필요 없다(21 §2).

4. 자주 겪을 일 넷과 답

겪는 일 무슨 뜻인가 무엇을 하면 되나
「못 뽑았다」가 여럿 변환 도구가 없거나 파일이 옛 판이다 운영자에게 갈래를 알린다(73)
찾기 결과가 엉뚱하다 뜻 검색이 꺼졌거나 임베더가 못 가려낸다 화면의 「뜻 검색」 상태를 본다
오래 걸린다 2.2 GB 를 훑는 중이다 진행 표시를 본다 · 중간에 멈춰도 대장은 남는다
모델이 「모른다」고 한다 정상이다 — 자료에 없는 것이다 자료를 더 넣거나 물음을 바꾼다

★★★ 마지막 줄이 사용자 문서의 핵심이다. 「모른다」가 고장이 아니라 바른 동작임을 문서가 먼저 말해 두지 않으면 사람은 그것을 결함으로 신고한다.

5. 아직 없는 것