도움말 글쓰기 소소한 원칙

도움말 작성 도구(매뉴얼웍스)를 만들지만, 남들이 모를 도움말 글쓰기 노하우는 없습니다. 도움말 글쓰기는 도구와 상관이 없습니다. 메모장으로 좋은 도움말을 쓸 수 있습니다. 도움말(사용자 가이드와 설치 가이드)을 쓰면서 고민했던 것을 기록합니다. 도움말 작성을 위한 소소한 원칙이 첫 번째 글입니다.

도움말의 중요성 공감하기

시간에 쫓기는 제품 개발과 SI 프로젝트 막바지에 짬짬이 도움말을 작성하는 풍경은 익숙합니다. 매뉴얼웍스를 개발한 동기입니다. 시간이 없으니 얼기설기 만들고 천천히 채워나가자고 다짐합니다. 세월이 흘러도 처음 모습 그대로입니다. 쓰임새가 없으니 잊습니다.

도움말을 썼다는 사실이 중요할 뿐 도움말 내용과 완성도에는 관심을 두지 않습니다. 이 글에서 도움말의 중요성을 나열할 생각은 없습니다. 도움말의 중요성을 공감하는 분위기가 성공적인 도움말 글쓰기의 토양입니다. 좋은 밭에서 맛있는 과일이 여뭅니다. 매뉴얼웍스 고객 모두는 도움말의 중요성을 공감하고 있습니다. 도움말 글쓰기의 첫 번째 걸음은 매뉴얼웍스 도입입니다.

맞춤법과 띄어쓰기에 주의하고 틀린 문장 쓰지 않기

대부분 글쓰기가 본업이 아닌 사람이 도움말을 작성합니다. 그러다 보니 맞춤법과 띄어쓰기 실수가 잦습니다. 간단한 검색으로 맞춤법과 띄어쓰기 실수를 줄일 수 있습니다. 그만큼의 시간과 노력이 아까워서는 좋은 도움말 글쓰기는 어렵습니다.

국립국어원 표준국어대사전이나 네이버 국어사전 등의 인터넷 국어사전이 있습니다. 부산대학교 인공지능연구실과 (주)나라인포테크가 제공하는 한국어 맞춤법/문법 검사기도 도움을 줍니다.

간결하게 쓰기

대중적 글쓰기는 문장이 짧아도 문제입니다. ‘나의 문화유산답사기’를 쓴 유홍준은 ‘글 길이에 따라 호흡이 달라야 한다. 문장이 짧으면 튀고, 길면 못 쓴다.’라고 했습니다. 그렇지만 아름다움을 추구하지 않는 도움말 글쓰기는 최대한 문장을 짧게 씁니다.

주어와 서술어의 어긋남이 도움말 틀린 글의 주요 원인입니다. 복문은 피하고 단문을 사용합니다. 형용사와 부사를 생략하면 주어와 서술어의 어긋남을 피할 수 있습니다. 형용사(구체적인)와 서술격 조사(있습니다)를 생략하면 글이 깔끔해집니다. 의미 전달도 충분합니다.

교정 전

이 관리자 가이드는 쓰리래빗츠의 구체적인 사용 방법을 각 부로 나누어 설명하고 있습니다.

교정 후

이 관리자 가이드는 쓰리래빗츠의 사용 방법을 각 부로 나누어 설명합니다.

군더더기 덜어내기

도움말 읽는 사람의 지적 능력을 과소평가하지 않습니다. 예를 들어 쓰리래빗츠 설치 가이드 시스템 요구 사항 장에서 자바 버전 정책을 설명하고 있습니다. 군더더기입니다. 단락 전체를 삭제합니다.

자바 버전은 6.0, 7.0, 8.0 등과 1.6, 1.7, 1.8 등으로 이중 표기됩니다. 8.0과 1.8은 같은 버전을 지칭합니다.

다음 글은 쓰리래빗츠는 자바로 개발했기에 쓰리래빗츠를 사용하려면 자바를 설치해야 함을 설명합니다. 사용자가 쓰리래빗츠의 개발 언어를 알 필요는 없습니다. 군더더기입니다.

교정 전

쓰리래빗츠는 자바로 개발한 소프트웨어로 이를 실행하려면 운영체제에 오라클 자바 8.0 이상을 설치해야 합니다.

교정 후

쓰리래빗츠를 실행하려면 운영체제에 오라클 자바 8.0 이상을 설치해야 합니다.

과도하게 친절한 설명도 군더더기입니다.

교정 전

장 제목을 클릭하면 해당 장을 편집할 수 있는 에디터가 열립니다.

교정 후

장 제목을 클릭하면 에디터가 열립니다.

일관성 지키기

대중적 글쓰기에서 같은 뜻을 같은 단어로 반복한 글은 지루합니다. 도움말 글쓰기는 다릅니다. 뜻이 같다면 같은 단어를 사용합니다. 전체 단어 숫자가 작을수록 좋습니다. 단어뿐만 아니라 문장도 마찬가지입니다.

한글을 한글답게

도움말 글쓰기에서 한글을 한글답게 쓰자는 주장은 시간과 비용을 염두에 두지 않는 한가한 주장일 수 있습니다. 맞습니다. 시간 여유가 있고 한글을 사랑한다면 한글을 한글답게 썼으면 하는 바람입니다.

첫 번째로 우리말 단어를 쓰도록 노력합니다. 어색한 조어를 만들어 외래어를 대체하자는 것은 아닙니다. 메뉴와 아이콘을 대체할 우리말은 떠오르지 않습니다. 다운로드를 내려받기로 클릭을 누르기로 바꾸는 것에는 거부감이 없습니다. 두 번째로 외국어 번역에 영향을 받은 문장을 우리글답게 씁니다. ‘되다’ 보다 ‘하다’를 쓰는 것이 그 예입니다. 쓰리래빗츠 도움말에서 이렇게 교정한 사례입니다.

사용자 입장에서 작성하기

시간에 쫓기면 메뉴 또는 화면 단위로 소프트웨어 도움말을 작성합니다. 안타까운 현실입니다. 매뉴얼웍스 사용자 누구도 특정 메뉴나 화면 사용 방법을 묻지 않습니다. 사용자는 자신이 하고 싶은 것을 묻습니다. 예를 들어 웹 뷰어 로고를 바꾸는 방법을 묻지 <환경 설정 | 일반 설정(이 메뉴에 웹 뷰어 로고를 바꾸는 기능이 있음)> 메뉴 설명을 요청하지 않습니다.

매뉴얼웍스가 DITA를 지원하지는 않지만, 그 철학에 100% 공감합니다. 사용자가 원하는 행위(Task)와 알고 싶은 지식(Concept)을 중심으로 도움말을 작성합니다. 소프트웨어 개발 방법론의 발전에도 불구하고 현장에서는 화면 설계가 요구 사항 분석과 설계 단계의 중심입니다. 이 관행이 도움말 작성에도 영향을 미칩니다. 메뉴와 화면 단위로 도움말을 작성하는 이유입니다.

소프트웨어 개발 방법의 오랜 관행을 바꾸는 건 어렵지만 행위와 지식을 중심으로 도움말을 작성하는 건 괜찮은 도전입니다. 고객 질문에 도움말 링크를 보내는 것으로 답할 수 있게 도움말을 구성하는 것을 상상하면 목표가 뚜렷합니다.

어설픈 이 글이 틀리거나 이 글과 생각이 다를 수 있습니다. 쓰리래빗츠 이름으로 나온 도움말에서 이 원칙을 지키지 않은 것을 쉽게 찾을 수 있습니다. 게으름이 첫 번째 이유고, 원칙을 소화하지 못했음이 두 번째 이유입니다. 더디지만 쓰리래빗츠 도움말도 조금씩 바꿔나가고 있다는 변명으로 글을 마무리합니다.