Close

더 나은 설명서 작성

방금 프로젝트를 시작했으며 이제 설명서를 제공해야 합니다(단서: $#*&^!%).

처음에는 막막해 보입니까? 물론 그럴 수 있습니다. 하지만 저희가 도와드리겠습니다. 아래에서 프로세스를 안내하는 전문가 팁이 포함된 단계별 가이드, 즉 설명서에 대한 설명서를[(윙크)] 찾을 수 있습니다.시작해 보겠습니다!


왜 관심을 가져야 합니까?

간단히 말해서 설명서는 사용자가 필요한 작업을 수행하는 데 도움이 됩니다. 그러나, 대부분의 설명할 수 없는 놀라운 일과 마찬가지로 단순히 사용자가 일을 완료하도록 돕는 것 이상의 역할을 합니다. 설명서는 사용자 및 팀이 다음을 할 수 있도록 돕습니다.

정신적인 에너지 소모 감소

너무 많이 생각하지 않고, 가능한 한 최소한의 노력으로 작업을 완료합니다.

일관성 유지

독자가 동일한 정보, 프로세스 및 계획을 일관된 방식으로 사용하도록 합니다.

워크로드 최소화

바로 작업을 시작할 수 있도록 팀원을 빠르고 효율적으로 온보딩합니다.

회사 브랜딩 향상

외부 고객과 내부 직원을 지원하고 도움이 되려고 한다는 것을 알립니다.

가치를 제공하지 않는다면 아무도 여러분의 방향에 관심을 보이지 않습니다. 독자가 제공된 정보에 대해 생각하는 방식을 형성할 수 있도록 하고 관심을 가져야 하는 이유를 독자에게 교육하는 것이 여러분이 해야 할 일입니다.

설명서란 무엇입니까?

설명서는 여러분이 생각하는 것처럼 즉 일련의 문서입니다. 일반적인 최종 사용자를 위한 나침반입니다. 소프트웨어 엔지니어를 위한 플레이북입니다. 보다 기술적인 영역에서 설명서는 일반적으로 소프트웨어와 함께 제공되는 텍스트 또는 일러스트레이션입니다. 이러한 설명서는 작동 방식, 운영 방식 및 사용 방법을 설명하는 참조 가이드 역할을 합니다. 소프트웨어 팀은 제품 요구 사항, 릴리스 정보 또는 디자인 사양에 대해 이야기할 때 설명서를 참조할 수 있습니다. 기술 팀은 설명서 를 사용하여 코드 및 API를 자세히 설명하고 소프트웨어 개발 프로세스를 기록할 수 있습니다. 외부적으로 설명서는 시스템 관리자, 지원 팀 및 기타 최종 사용자를 위한 설명서 및 사용자 가이드의 형태를 취하는 경우가 많습니다.

모든 설명서는 다음 2가지 주요 목표를 달성하려고 해야 합니다.

1. 사용자에게 정보 제공

2. 사용자가 무언가를 성공적으로 성취할 수 있도록 지원

설명서를 시작할 때 먼저 관심 토픽, 목표 또는 목적을 정의하여 대상 그룹이 읽고 있는 내용을 바로 이해할 수 있도록 돕습니다.

설명서의 유형

앞서 언급한 것처럼, 설명서 는 모든 형태와 크기로 내부 및 외부에 제공됩니다. 설명서 유형에 따라 음색, 어조, 형식, 기여자, 대상 그룹 및 콘텐츠가 다릅니다. 가장 일반적인 유형은 다음과 같습니다.



내부 설명서
팀-설명서-일러스트레이션

팀 문서

팀 설명서는 팀이 하나의 팀이 되어 효율적으로 일할 수 있도록 수행하고 있는 작업을 명확하게 보여 줄 수 있습니다. 이러한 설명서는 프로젝트 계획, 팀 일정, 상태 보고서, 미팅 노트를 비롯해 팀이 기능적이고 효율적으로 작업하는 데 필요한 모든 형태로 제공됩니다. 이 유형의 설명서는 모두가 동일한 정보를 공유할 수 있도록 자세히 기술되어 있습니다.

참조-설명서-일러스트레이션

참조 설명서

참조 설명서는 회사에 중요한 토픽, 프로세스 및 정책을 교육합니다. 여기에는 HR 부서에서 만든 정책, 외부 공급업체 채용에 대한 법무 프로세스 또는 회사 복리후생 설정에 대한 방법 안내 게시물이 포함될 수 있습니다. 참조 설명서는 소규모 인력 풀에서 다양한 대규모 대상을 위해 작성하므로 쉽게 이해할 수 있는 콘텐츠가 중요합니다.

프로젝트-설명서-일러스트레이션

프로젝트 설명서

프로젝트 설명서는 당연히 프로젝트에 따라 다르며 프로젝트 개발에 필요한 구조를 제공합니다. 여기에는 제안, 제품 요구 사항 설명서, 설계 가이드라인 또는 스케치, 로드맵 및 개발에 필요한 기타 관련 정보와 프로젝트 관리자, 엔지니어, 디자이너 등이 제공하는 기고물이 포함됩니다.



외부 설명서
시스템-설명서-일러스트레이션

시스템 설명서

시스템 설명서에는 제한 사항 및 요구 사항뿐 아니라 코드, API 및 개발자와 프로그래머에게 특정 소프트웨어를 개발하는 데 사용할 수 있는 방법 및 기능의 종류를 알려주는 기타 프로세스가 자세히 설명되어 있습니다. API 호출 및 응답과 같은 코드 조각은 이러한 유형의 설명서에서 핵심입니다.

최종 사용자-설명서-일러스트레이션

최종 사용자 설명서

사용자 설명서는 가장 눈에 잘 띄는 유형의 설명서입니다. 읽고 이해하기 쉬워야 하며 각각 새 버전의 소프트웨어로 업데이트되어야 합니다. 사용자 설명서는 "추가 정보" 설명서, 설치 가이드, 관리자 가이드, 제품 기술 자료, 자습서(가장 유용한 정보)의 형태로 제공됩니다. 또한 참조 설명서와 마찬가지로 소규모 작성자 풀에서 대규모 소비자 풀을 위해 작성하므로 쉽게 이해할 수 있는 콘텐츠가 중요합니다.

설명서에 예시를 포함하면 대상 그룹에게 큰 가치를 제공합니다. 예시는 개념과 아이디어를 이해하는 데 도움이 되는 다리 역할을 하며 설명서를 읽는 사용자가 여러분이 설명하고 있는 내용에 대해 확신을 가질 수 있도록 합니다.

설명서 만들기

궁극적인 목표는 독자에게 유용한 설명서를 제공하는 것입니다. Atlassian은 작업을 좀 더 쉽게 할 수 있도록 아래 설명서에 대한 자습서 형식의 설명서를(메타 설명서) 제공했습니다.

1. 조사

사용자가 제품, 프로젝트 또는 API에 대해 알아야 하는 것은 무엇입니까? 분석 도구를 사용하여 검색 내용을 보고, 온라인 커뮤니티 포럼 및 토론 그룹을 찾아보고, 사용자 검색 및 사용성 테스트를 수행할 수 있습니다. 또한 제품과 사용자 질문, 새로운 기능, 워크플로를 쉽게 설명할 수 있는 방법을 알고 있어야 합니다.

2. 바로 시작

설명서에서 다룰 내용과 독자에게 유용한 이유를 분명하게 설명하는 것으로 시작합니다.

3. 세부 사항 캡처

개요를 만들고 콘텐츠의 초안을 작성합니다. 대상 그룹에게 적합한 목소리 및 인간적인 어조로 작성하고 일관되고 간결한 언어를 사용합니다. 중요한 세부 사항을 명확하게 전달합니다.

4. 형식

처음부터 끝까지 쉽게 따라갈 수 있도록 페이지를 구성합니다. 중요하지 않은 콘텐츠를 제거하고 다이어그램, 스크린샷, 이미지와 같은 시각 자료로 긴 콘텐츠를 세분화합니다.

5. 검토

문장에 대한 피드백을 받습니다. 검토자가 설명서의 목적을 이해하고 있는지 확인합니다. 이렇게 하면 검토자가 혼동되는 언어를 찾아내거나 누락된 단계를 알려줄 수 있습니다.

6. 게시

수정 및 편집이 끝나면 바로 배포할 수 있습니다! 작업을 게시하고 피드백과 의견에 귀를 기울이세요. 설명서는 배포하고 잊어버리는 것이 아닙니다.

핵심 사항

설명한 것처럼 설명서는 단순히 여러 설명과 단어를 합쳐 놓은 것이 아닙니다. 이상해 보일 수 있지만 그럴 만한 이유가 있습니다. 설명서를 만드는 전체 과정에서 다음과 같은 기본 원칙을 기억하세요.

간략하게 유지

설명서에는 지원 티켓을 제기하지 않고도 작업을 완료할 수 있도록 적당한 양의 정보가 포함되어 있어야 합니다. 독자가 더 자세한 내용을 파악할 수 있도록 핵심 요점과 옵션 을 제공합니다.

시각 자료가 핵심

시각 자료는 이해를 돕는 데 핵심적인 부분입니다. 제품 디자인, 코드 샘플, 제품 내 데모, 스크린샷, 동영상 자습서는 독자가 개념, 방법, 해야 할 일을 완전히 이해하는 데 있어서 큰 역할을 합니다. 또한 레이아웃, 가독성 및 쉽게 이해할 수 있는 분량에 유의하세요.

대상 그룹 이해하기

사용자의 입장에서 생각하세요. 독자를 이해하고, 제품 및 설명서에 대한 사용자 여정을 살펴보세요. 이 원칙을 항상 작성 방법 및 작성 내용의 가이드로 삼아야 합니다.

바로 작업을 시작할 수 있습니다.

최고의 설명서는 명확하고 간결하고, 유용한 정보를 제공하며, 가장 중요한 것은 대상 그룹을 위한 가치를 제공합니다. Confluence 와 같은 설명서용 팀 협업 소프트웨어를 살펴보고 검색 시간을 단축하고 생산적인 활동에 전념하세요.

자세히 알아보기