소프트웨어 문서란 무엇입니까? 시작하기 위한 유형 및 모범 사례

개발자와 최종 사용자가 소프트웨어에서 최대한 많은 가치를 얻도록 하려면 고품질 소프트웨어 문서를 작성해야 합니다.

그러나 소프트웨어 문서란 실제로 무엇이며 프로젝트를 위해 문서를 만드는 방법은 무엇입니까?

이 게시물에서는 다음을 포함하여 소프트웨어 문서에 대해 알아야 할 모든 것을 파헤칠 것입니다.

• 소프트웨어 문서란 무엇입니까?
• 다양한 유형의 소프트웨어 문서(예제 포함)
• 소프트웨어 문서를 게시하는 방법(최고의 도구)
• 양질의 소프트웨어 문서 작성을 위한 몇 가지 모범 사례

파헤쳐 보자!

소프트웨어 문서란 무엇입니까?

소프트웨어 설명서는 최종 사용자, 개발자 및/또는 직원이 소프트웨어를 이해하고 이를 사용하여 목표를 효과적으로 달성하는 데 도움이 되는 콘텐츠입니다.

일반적으로 웹 사이트에 소프트웨어 설명서를 게시합니다. 그러면 사람들이 액세스하여 소프트웨어와 작동 방식에 대해 자세히 알아볼 수 있습니다.

소프트웨어 문서의 광범위한 정의 내에는 다양한 유형의 소프트웨어 문서가 있습니다. 다음에 그것에 대해 논의합시다.

다양한 유형의 소프트웨어 문서

서로 다른 유형의 소프트웨어 문서를 몇 가지 광범위한 범주로 대략 나눌 수 있습니다.

첫 번째 고려 사항은 문서가 어떤 유형의 사람을 대상으로 하는지입니다.

• 사용자 설명서 – 제품의 최종 사용자를 위해 만든 설명서입니다. 특별한 기술 지식이 있을 수도 있고 없을 수도 있는 일반 사용자의 관점에서 소프트웨어를 사용하는 방법을 이해하는 데 도움이 됩니다.
• 개발자 문서 – 이것은 API 문서와 같이 개발자를 위해 만든 보다 기술적인 소프트웨어 문서입니다.

두 번째 고려 사항은 문서가 외부 또는 내부 청중을 대상으로 하는지 여부입니다.

• 외부 소프트웨어 설명서 – 사용자를 돕기 위해 만든 공개 설명서입니다.
• 내부 소프트웨어 문서 – 이것은 직원들이 보다 효율적으로 작업하고 주요 세부 사항을 이해하는 데 도움이 되도록 만든 개인 문서입니다.

예를 들어 소프트웨어 작업에 도움이 되는 내부 팀용 개발자 문서 세트와 외부 개발자용 공개 개발자 문서 세트가 있을 수 있습니다.

이러한 유형의 소프트웨어 문서를 좀 더 자세히 분석해 보겠습니다.

개발자 문서에 대한 소프트웨어 문서 예제

• API 설명서 – 소프트웨어의 API와 상호 작용하는 방법을 개발자에게 보여줍니다.
• Readme – 소프트웨어를 소개하고 기능을 설명합니다. 일반적으로 사람들이 가장 먼저 읽는 것입니다.
• 릴리스 정보 – 중요한 변경 사항을 포함하여 소프트웨어의 새 릴리스를 문서화합니다.
• 아키텍처 문서 – 잠재적으로 다이어그램을 포함하여 소프트웨어의 구조를 보여줍니다.
• 데이터 모델 문서화 – 다양한 데이터 구조 간의 관계를 포함하여 소프트웨어의 다양한 데이터 구조를 문서화합니다.
• 프로세스 문서화 – 버그 보고서, 로드맵, 품질 보증, 테스트 프로토콜 등과 같은 주요 프로세스를 문서화합니다.

개발자 중심 문서의 실제 소프트웨어 문서 예제를 보려면 다음과 같은 다양한 주제를 다루는 Gravity Forms의 "개발자" 문서를 볼 수 있습니다.

• PHP 후크(WordPress용)
• 데이터 객체
• PHP API
• 데이터 베이스
• REST API

예를 들어 REST API 설명서는 다음과 같습니다.

사용자 문서의 소프트웨어 문서 예

• 시작 가이드 – 소프트웨어를 빠르게 시작하고 실행하는 방법을 사용자에게 보여줍니다.
• 특정 사용 사례에 대한 자습서 – 특정 작업을 수행하기 위한 보다 구체적인 자습서입니다.
• 용어집/참조 설명서 – 사용자가 주요 용어 및 세부 정보를 이해하도록 돕습니다.
• FAQ – 자주 묻는 질문에 답변합니다.

보다 사용자 중심적인 소프트웨어 문서가 어떻게 생겼는지에 대한 실제 예를 보려면 위에서 동일한 Gravity Forms 예를 참조하십시오.

Gravity Forms의 보다 사용자 중심적인 기사를 보면 용어집 및 주요 기능에 대한 설명과 함께 소프트웨어 인터페이스를 사용하여 작업을 수행하는 방법에 대한 단계별 자습서를 많이 볼 수 있습니다.

개발자 소프트웨어 문서와 비교할 때 더 많은 스크린샷과 일반 언어 설명 및 훨씬 적은 코드 블록을 볼 수 있습니다.

소프트웨어 문서 게시 방법: 세 가지 최고의 소프트웨어 문서 도구

웹 사이트에 소프트웨어 설명서를 게시하려면 전용 소프트웨어 설명서 도구 또는 특정 유형의 지식 관리 시스템이 필요합니다.

이 섹션에서는 최고의 소프트웨어 문서화 도구 중 일부를 신속하게 다룰 것입니다. 그런 다음 다음 섹션에서는 양질의 문서 작성을 위한 몇 가지 모범 사례를 살펴보겠습니다.

여기에서 더 자세히 살펴보고 싶다면 최고의 문서화 도구 및 최고의 기술 문서화 소프트웨어에 대한 전체 가이드를 읽어보십시오.

영웅 지식 기반

Heroic Knowledge Base는 인기 있는 오픈 소스 WordPress 소프트웨어에 대한 문서 및 지식 기반 플러그인입니다.

Heroic 기술 자료를 사용하면 효과적인 소프트웨어 문서를 작성하는 데 필요한 모든 기능에 계속 액세스하면서 문서를 자체 호스팅하고 완전한 제어를 유지할 수 있습니다.

다음은 Heroic Knowledge Base에서 얻을 수 있는 몇 가지 핵심 기능입니다.

• 콜아웃 및 기타 중요한 스타일 세부 정보를 위한 내장 블록을 포함하는 유연한 콘텐츠 편집기 .
• 자동 목차를 통해 사용자는 문서 문서에서 다루는 콘텐츠를 빠르게 확인하고 특정 섹션으로 이동할 수 있습니다.
• 기본 WordPress 개정 시스템을 통한 개정 제어 및 버전 기록 .
• 실시간 제안, 범주 등을 포함하는 실시간 Ajax 검색을 포함한 콘텐츠 검색 기능 .
• 사람들이 기사를 유용하거나 도움이 되지 않는 것으로 평가하고 피드백을 공유할 수 있는 사용자 피드백 시스템입니다 .
• 검색 분석을 통해 사용자가 검색하는 내용과 결과가 0인 검색어를 확인할 수 있습니다.
• 사용자가 사이트 어디에서나 소프트웨어 문서를 검색하고 액세스할 수 있도록 하는 즉각적인 답변 위젯입니다 .

Heroic Knowledge Base와 WordPress는 자체 호스팅 및 오픈 소스이기 때문에 필요에 따라 설정을 자유롭게 수정할 수도 있습니다.

암호, 사용자 계정, IP 주소, 인트라넷 등과 같은 다양한 전술을 사용하여 문서를 공개하거나 문서에 대한 액세스를 제한할 수 있습니다.

Heroic Knowledge Base는 연간 $149부터 시작합니다.

문서 읽기

문서 읽기는 개발자 문서 작성을 돕는 데 중점을 둔 문서 도구입니다.

특히 기술 개발자 문서 작성에 중점을 둔 경우 고려해야 할 또 다른 좋은 옵션이 될 수 있습니다.

Git을 사용하여 콘텐츠 및 업데이트 기록을 관리한 다음 프런트엔드 인터페이스에 문서를 배포할 수 있습니다.

Read the Docs의 다른 주목할만한 기능은 다음과 같습니다.

• 사용자가 무엇을 읽고 검색하는지 확인할 수 있는 기본 분석 기능 .
• 여러 동시 빌드를 지원합니다 . 이는 소프트웨어의 여러 버전을 제공하는 경우 유용할 수 있습니다(예: 버전 1.0용 문서 세트와 버전 2.0용 문서 세트).
• PDF, HTML 및 epub를 포함한 다양한 형식으로 문서를 내보냅니다 .
• 사용자가 문서를 찾는 데 도움이 되는 실시간 검색 제안.

Read the Docs는 오픈 소스 소프트웨어 프로젝트가 있는 경우 무료로 사용할 수 있습니다.

상용 소프트웨어 제품의 경우 월 $50부터 시작하는 유료 Read the Docs for Business 서비스가 있습니다.

GitBook

GitBook은 GitHub 및 GitLab 리포지토리를 모두 지원하는 Git을 사용하여 문서를 관리할 수 있는 또 다른 기술 소프트웨어 문서 도구입니다.

또는 Git을 사용하지 않으려면 GitBook을 사용하여 텍스트 편집기를 사용하여 문서를 만들거나 markdown 또는 .doc 파일에서 가져올 수도 있습니다.

GitBook이 제공하는 다른 주목할만한 기능은 다음과 같습니다.

• 개정 및 버전 기록을 추적하기 위한 버전 관리 .
• 여러 작성자가 기사를 공동 작업해야 하는 경우 유용한 실시간 팀 편집 .
• "공백" 및 "컬렉션"을 사용하여 기사를 구성하십시오 . 각 스페이스는 내부에 여러 컬렉션을 가질 수 있습니다.
• 사용자가 문서를 PDF 다운로드로 쉽게 내보낼 수 있는 PDF 내보내기 옵션입니다.

GitBook은 비영리 또는 오픈 소스 프로젝트에 무료입니다.

상용 소프트웨어 프로젝트의 경우 GitBook은 사용자당 월 $8부터 시작하며 최소 사용자는 5명입니다. 즉, 가장 저렴한 월 요금은 월 $40입니다.

소프트웨어 문서 작성을 위한 모범 사례

마지막으로 효과적인 문서 작성에 도움이 되는 몇 가지 소프트웨어 문서 모범 사례를 살펴보겠습니다.

사용자의 목표와 요구에 대해 생각

소프트웨어 설명서 기사를 작성할 때 다음과 같은 몇 가지 기본 질문에 답하는 것부터 시작하는 것이 중요합니다.

• 작성 중인 사용자는 누구입니까?
• 사용자가 달성하려는 것은 무엇입니까?
• 사용자의 기술 지식 수준은 어느 정도입니까?

이러한 질문에 대한 답을 알면 어떤 콘텐츠를 다룰 것인지, 가장 최적의 방식으로 문서를 구성하는 방법을 이해하는 데 도움이 됩니다.

예를 들어 소셜 미디어 예약 소프트웨어를 제공하고 소셜 미디어 관리자가 첫 번째 소셜 미디어 게시물을 예약하는 데 도움이 되는 기사를 작성한다고 가정해 보겠습니다.

소프트웨어 설명서를 작성할 때 일반 최종 사용자가 해당 목표를 달성할 수 있는 가장 간단한 방법을 보여주는 데 집중하고 싶을 것입니다.

개발자가 자체 통합을 설정할 수 있도록 API도 제공하는 경우 다른 문서에서 해당 방법을 언급하고 연결할 수 있습니다.

개발 프로세스에 소프트웨어 문서 포함

소프트웨어 문서를 작성할 때 문서화를 위해 프로젝트가 완료될 때까지 기다리는 함정에 빠지기 쉽습니다.

그러나 문서화되기 전에 새 기능이나 변경 사항을 제공할 수 있으므로 문서 부채로 빠르게 이어질 수 있습니다.

이를 방지하려면 소프트웨어 문서를 소프트웨어 개발 주기의 의식적인 부분으로 만드십시오. 새로운 기능이나 제품이 아직 문서화되지 않은 경우 코드 자체가 완료되더라도 출시할 준비가 되지 않은 것입니다.

문서화를 소프트웨어 개발 프로세스의 핵심 요구 사항으로 만들면 출하하는 모든 항목에 적절한 문서가 수반되도록 할 수 있습니다.

일관된 서식 및 스타일 사용

사람들이 소프트웨어 문서로 보다 효과적으로 작업할 수 있도록 하려면 모든 문서에서 일관된 형식과 스타일을 사용하는 것이 중요합니다.

동일한 형식을 사용하면 독자가 소프트웨어 문서가 어떻게 구성되어 있는지 알 수 있으므로 필요한 정보에 더 쉽게 빠르게 액세스할 수 있습니다.

이러한 일관성을 유지하기 위해 전용 소프트웨어 문서 스타일 가이드를 만들 수 있습니다.

소프트웨어 문서 관리 도구에는 일관된 스타일을 적용하는 데 도움이 되는 기능이 포함될 수도 있습니다.

예를 들어 Heroic Knowledge Base 플러그인에는 주요 정보 또는 경고를 강조 표시하기 위한 사전 스타일 콜아웃이 포함되어 있습니다. 이를 사용하면 모든 문서에서 일관된 형식을 보장할 수 있습니다.

전문가를 사용하여 기술 문서 작성

사용자 대면 소프트웨어 설명서의 경우 내용을 작성하는 데 관련 전문가가 필요하지 않을 수 있습니다.

그러나 개발자 중심의 API 문서와 같은 보다 기술적인 소프트웨어 문서의 경우 해당 문서를 작성할 관련 기술 지식이 있는 사람을 지정하는 것이 좋습니다.

조직에 해당 직책에 고용할 리소스가 있는 경우 도메인 전문 지식을 갖춘 전담 기술 작가가 될 수 있습니다. 또는 개발자 중 한 명이 될 수 있습니다.

중요한 것은 작성자가 다른 기술 사용자에게 설명할 수 있을 만큼 충분히 깊은 수준에서 소프트웨어의 기술적 측면을 이해하고 있다는 것입니다.

사람들이 콘텐츠를 쉽게 찾을 수 있도록 만들기(검색/필터)

문서 라이브러리가 커짐에 따라 사용자가 자신의 요구 사항을 충족하는 문서 항목을 찾기가 더 어려워질 것입니다.

이 문제를 방지하려면 소프트웨어 설명서의 검색 가능성을 개선하는 데 집중해야 합니다.

첫 번째 전략은 문서를 유형별로 나누는 것입니다.

예를 들어 일반적으로 최종 사용자 문서를 개발자 소프트웨어 문서와 분리하려고 합니다.

그 안에서 카테고리를 사용하여 기사를 더 나눌 수도 있습니다. 기능, 사용 사례, 추가 기능 등 소프트웨어 제품에 논리적으로 적합한 범주를 사용할 수 있습니다.

위의 동일한 Gravity Forms 예제를 유지하면서 Gravity Forms가 최종 사용자 문서를 기능 유형별로 나누는 것을 볼 수 있습니다.

또 다른 유용한 검색 가능성 기능은 실시간 검색 제안입니다. 사용자는 검색 상자에 관련 쿼리를 입력하기 시작하고 해당 쿼리와 일치하는 문서 기사를 즉시 볼 수 있습니다.

많은 문서화 도구에는 Heroic Knowledge Base를 비롯한 내장 실시간 검색 기능이 포함되어 있습니다.

소프트웨어 설명서를 최신 상태로 유지

소프트웨어는 항상 변경되기 때문에 소프트웨어 설명서는 항상 진행 중인 작업입니다.

소프트웨어가 변경되면 이러한 변경 사항을 반영하도록 설명서를 즉시 업데이트해야 합니다.

그렇지 않으면 문서가 "도움이 되지 않을" 뿐만 아니라 실제로 사용자에게 혼란을 줄 수 있습니다.

이러한 업데이트가 이루어지도록 하려면 문서 및 업데이트 프로세스를 소유할 특정 사용자를 지정해야 합니다. 그렇게 하면 모든 것을 정확하게 유지할 책임이 누구에게 있는지 모호하지 않습니다.

고객 피드백을 사용하여 문서 개선

자체 팀이 소프트웨어 문서를 검토하고 업데이트하도록 하는 것 외에도 고객 피드백도 고려해야 합니다.

고객은 특정 소프트웨어 설명서 문서가 얼마나 유용한지(또는 잠재적으로 도움이 되지 않는지)에 대한 귀중한 정보와 이를 개선할 수 있는 방법에 대한 세부 정보를 제공할 수 있습니다.

고객 피드백 프로세스를 자동화하려면 고객 피드백을 위한 기본 제공 기능이 포함된 문서 관리 도구를 찾고 싶을 것입니다.

예를 들어 Heroic Knowledge Base 플러그인을 사용하면 사용자가 문서를 유용하거나 도움이 되지 않는 것으로 평가하고 선택적으로 자유 형식 피드백을 제공할 수 있습니다.

그런 다음 대시보드에서 이 모든 정보를 보고 개선해야 할 설명서 문서를 빠르게 찾을 수 있습니다.

지금 소프트웨어 문서화를 시작하십시오

소프트웨어 문서는 귀하와 귀하의 고객이 보다 효과적으로 작업하고 소프트웨어에서 더 많은 가치를 얻는 데 도움이 됩니다.

다양한 유형의 소프트웨어 문서가 있으므로 어떤 유형이 소프트웨어 프로젝트의 요구 사항과 일치하는지 생각하고 싶을 것입니다.

개발자 대 최종 사용자와 같은 다양한 유형의 고객뿐만 아니라 내부 또는 외부 팀에 대해 서로 다른 문서가 있을 수 있습니다.

효과적인 문서를 작성하려면 이 게시물의 모범 사례를 따르고 싶을 것입니다.

해당 문서를 게시하려면 강력한 WordPress 소프트웨어를 기반으로 하는 Heroic Knowledge Base와 같은 오픈 소스 도구를 사용할 수 있습니다.

고품질 소프트웨어 문서를 게시하는 데 필요한 모든 기능을 갖춘 자체 호스팅 플랫폼의 유연성과 소유권을 얻게 됩니다.

자세한 내용을 보려면 여기를 클릭하여 Heroic Knowledge Base로 이동하십시오.