고객 사용자를 위한 IT 프로젝트의 화면/기능에 대한 도움말은 어떻게 만들고 계신가요?

IT 프로젝트에서 문서화의 품질은 이해당사자 간의 합의, 즉 프로젝트 관련자들이 문서화의 필요성과 중요성에 대해 동일한 이해를 하고 있는지가 중요합니다.

문서화는 시간과 비용이 많이 소요되는 작업이기 때문인데, 이들이 문서화의 목표와 방향에 대해 합의하면, 문서화의 품질과 정보 공유의 만족도가 좋아질 가능성이 높아집니다.

작성하게 되는 문서 분류는 크게 세 가지 주요 그룹을 대상으로 구성되어 있습니다.

• 첫 번째 그룹은 고객 사용자들로, 제품이나 서비스에 대한 이해를 돕고, 고객의 요구사항을 충족시키는 데 초점을 맞추고 있습니다. 이러한 문서는 사용자 설명서, FAQ, 제품 사양서 등을 포함할 수 있습니다.
• 두 번째 그룹은 운영 업무를 담당하는 사람들로, S/W, H/W, N/W 아키텍처, 내부 프로세스, 시스템 구조, 환경설정 문서화 등에 대한 정보를 제공하는 데 중점을 두고 있습니다. 이러한 문서는 운영 업무에 필요한 기술 사양서, 시스템 아키텍처, 프로젝트 관리 문서 등을 포함할 수 있습니다.
• 세 번째 그룹은 개발 업무를 담당하는 사람들로, 이들에게 제공되는 문서는 주로 소프트웨어 개발, 시스템 아키텍처, 소스코드, 데이터 정보, 배포 관리 등에 대한 정보를 제공하는 데 중점을 두고 있습니다. 이러한 문서는 개발 가이드라인, 코드 문서화, 시스템 아키텍처 문서 등을 포함할 수 있습니다.

제가 주로 풀 스택으로 웹 개발을 하다 보니 웹 분야에 중점을 둔 내용이긴 합니다만, 이 중에서 개발자의 관점으로 첫 번째 그룹인 고객 사용자들을 위한 도움말을 어떻게 저비용으로 고효율을 만들고 유지할 수 있을까? 생각해 보았는데, 그 이유는 고객 사용자들과 직접적인 합의가 어렵기 때문입니다.

대부분은 IT 프로젝트의 문서화에 대한 지침이 없으므로, 먼저 IT 프로젝트에서 특정 화면이나 기능에 대한 도움말 문서를 작성해야 할 때 따라 할 수 있는 주어진 상황에 따라 적용할 수 있는 간단한 기준을 만들어봤습니다.

• 읽는 대상 요구 파악하기: 누가 이 문서를 사용하게 될지 파악하고, 가능하다면 당사자의 요구를 확인하고 그것에 맞게 문서를 조정하는 것이 지름길입니다.
• 튜토리얼 또는 레퍼런스를 작성하기: 사용자가 기능을 더 잘 이해하거나 사용하는 데 도움이 될 수 있는 추가 정보와 함께 화면/기능에 대한 사용 방법을 명확하게 설명하는 상세한 단계별 튜토리얼 또는 참조 가이드를 만듭니다.
• 단순하게 만들기: 대부분은 문서가 길어지면 안 봅니다. 의도적으로 명확한 고객이 이해할 수 있는 전문 용어를 사용하세요. 필요한 경우에만 자세한 설명을 제공하세요.
• 검색할 수 있게 만들기: 검색하기 쉬운 방식으로 문서를 정리하세요. 기능과 관련된 키워드를 사용하고 관련 주제나 기능에 대한 링크를 제공하세요. 사용자가 필요한 정보를 빠르게 찾을 방법이 필요합니다.
• 최신 상태로 유지하기: 화면/기능이 추가 되거나 개선함에 따라 문서도 반영되어야 합니다.

문서의 품질은 사용자가 기능을 인식하고 사용하는 방식에 도움을 주기 때문에 시간을 들여 일관성 있고 명확하며 사용자 친화적인 도움말 가이드를 작성하는 것이 좋습니다. 약간의 노력이 필요할 수도 있지만 그만한 가치가 있습니다.

제가 고객 사용자를 위해 작성해 본 정보 형식은 워드나 파워포인트 파일을 PDF로 제공하는 문서 외에 고객 만족도가 좋았던 기능들은 다음과 같습니다.

• HTML/Markdown 에디터로 만든 내용을 링크
• 주요 입력 항목에 움직이는 애니메이션 placeholder 제공
• 화면 내 주요 항목에 툴팁 제공
• 화면 내 하드 코딩된 도움 문장을 보여주거나 숨기기
• 화면 내 단계별로 동작하는 가이드 팝업

이 기능들을 위해 사용하는 오픈소스는 다음과 같습니다.

• https://marked.js.org: Markdown 내용을 HTML 문서로 변환하며 다양한 옵션을 제공해 줍니다.
• https://github.com/chinchang/superplaceholder.js: 텍스트 박스에 여러 도움 문장을 순환하여 표시하는 생동감을 불어넣습니다.
• https://introjs.com: 적은 노력으로 단계별로 고객을 위한 온보딩 투어를 생성합니다.
• https://atomiks.github.io/tippyjs: 화면에 특정 요소들의 툴팁, 팝오버에 스타일링을 제공합니다.

다른 웹, CLI/GUI 응용 프로그램, 기타 IT 프로젝트에서 고객 사용자를 위한 IT 프로젝트의 화면/기능에 대한 도움말은 어떻게 만들고 계시는지 궁금하네요.