What style of documentation should product managers use in order to communicate the appropriate message?

문서화는 모든 오픈소스 프로젝트에서 가장 중요하면서도 과소평가되는 구성 요소 중 하나이며, 결코 가볍게 여겨서는 안 됩니다.

대부분의 오픈소스 프로젝트는 충분한 관심을 받지 못합니다. 이는 주로 개발자들이 API와 제품 문서를 위한 효과적인 문서 환경을 만드는 데 관심이 없거나, 능력이 부족하거나, 시간이 없기 때문입니다.

아무리 뛰어난 애플리케이션이라도 문서가 부실하면 사용자들은 그 혜택을 누릴 수 없습니다.

또한 어떤 이유로든 사용자들이 그 애플리케이션을 사용해야만 하는 상황이라도, 효과적으로 또는 개발자가 의도한 방식대로 사용하기 어렵습니다.

좋은 문서를 작성하는 방법을 이해하고 다른 문서 프로젝트를 정기적으로 검토하는 데는 상당한 노력이 필요합니다. Docsie의 다양한 문서를 작성해 본 경험에서 말씀드리자면, 여러분이 자신 외에 다른 사람이 사용할 코드를 개발하고 있다면, 특히 그 사용자가 고객이라면, 제품은 잘 문서화되고, 적절히 형식화되며, 동적으로 제시되어야 합니다.

튜토리얼, 하우투, 설명서, 참조 문서의 차이점은 무엇인가요?¶

많은 사람들이 이 네 가지 용어가 같은 것을 의미한다고 잘못 생각합니다. 하지만 각각은 서로 다른 의미를 가집니다. 이러한 다양한 유형의 문서는 매우 중요하며 주요 차이점이 있습니다:

튜토리얼 문서: 교육 목적의 정보 기반 문서입니다.

하우투 가이드/사용자 가이드 문서: 특정 목표를 달성하기 위해 일련의 단계를 통해 특정 문제를 해결하는 방법을 설명하는 문서입니다.

설명 문서: 다양한 설명과 배경 맥락을 통해 사용자/독자가 제품에 대한 깊은 이해를 얻을 수 있도록 설계된 아티클 형태의 문서입니다.

참조 노트 문서: 새로운 기능 업데이트와 용도에 대한 설명을 사용자에게 알려주기 위해 설계된 문서입니다. 이 유형의 문서는 개발자 문서 형태로 매우 '가공되지 않은' 상태일 수 있지만, 최종 사용자가 쉽게 이해할 수 있는 사용자 친화적인 릴리스 노트로 변환될 수도 있습니다.

고품질 문서를 작성하는 이유¶

계속 진행하기 전에, 능숙한 문서 작성이 오늘날 사회에서 왜 매우 중요하지만 과소평가되는 요구사항인지 이해하는 것이 중요합니다. 광범위하고 잘 작성된 문서의 가용성은 널리 채택되는 데 가장 중요한 기준 중 하나입니다. 특히 거의 모든 활동이 공개되고 이러한 활동이 프로젝트 성공에 중요한 역할을 하는 오픈소스 프로젝트에서 더욱 그렇습니다.

효과적인 문서를 작성하는 가장 중요한 이유를 살펴보겠습니다.

고객을 위한 더 나은 온보딩 경험을 제공합니다.¶

고객에게 제품에 대한 적절한 문서를 제공하면, 고객이 제품에 더 편안함을 느끼고 특정 지침으로 보호받는다고 느끼도록 도울 수 있습니다. 이를 위해서는 다음과 같이 해야 합니다:

1. 제품 문서가 눈에 잘 띄고 쉽게 접근할 수 있도록 하세요. 앱 내 링크나 검색 가능한 문서 플랫폼을 통해 제공하면 좋습니다.

2. 잘 작성되어 고객이 답을 빠르고 쉽게 찾을 수 있도록 하세요.

한 가지 팁은 문서를 한 번만 작성하면, 새로운 고객이 회사에 유입될 때마다 반복해서 활용된다는 점입니다.

지원 문의가 줄어듭니다.¶

문서를 읽고 이해하는 고객일수록 제품을 구매할 가능성이 높습니다. 고객이 무언가를 이해하지 못할 때 매우 좌절할 수 있으며, 제품을 탓하기 시작할 수 있습니다.

문제가 발생했을 때 일부 고객은 즉시 지원팀에 연락할 수 있지만, 문서가 매력적이고 접근하기 쉬우며 이해하기 쉽다면, 사용자는 여러분에게 문의하지 않고도 스스로 문제를 해결할 수 있어 더 자신감을 갖게 됩니다.

자체 팀을 지원하는 데 도움이 됩니다.¶

강력한 지식 베이스는 자체 팀원을 지원하는 데도 사용될 수 있습니다. 내부 팀은 새로운 기능, 계획된 로드맵, API 문서 및 모두가 동일한 정보를 공유하는 데 필요한 모든 것에 대해 알고 있어야 합니다.

효과적인 문서 작성 방법 단계별 가이드¶

문서의 내용을 작성하고 이 활동을 구성하는 것은 어떤 어조를 사용할지, 문서를 이해하기 쉽게 만드는 방법과는 완전히 다른 작업입니다. O'Reilly가 언급한 바와 같이, 좋은 문서의 8가지 규칙이 있습니다:

1. 독자를 끌어들이는 문서를 만드세요.

2. 프로젝트의 모든 영역을 다루는 철저한 문서를 작성하세요.

3. 이해하기 쉽고 빠르게 훑어볼 수 있는 자료를 만드세요.

4. 사례 연구를 통해 제품 사용 방법을 보여주는 문서를 만드세요.

5. 필요한 곳에 반복이 포함된 문서를 작성하세요.

6. 최신 상태를 유지하는 문서를 작성하세요.

7. 기여하기 쉬운 문서를 작성하세요.

8. 찾기 쉽고 이해하기 쉬운 문서를 작성하세요.

이러한 요소들은 주로 콘텐츠와 관련이 있습니다. 다음으로, 이 정보를 구성하는 "방법"에 대해 6단계로 살펴보겠습니다:

무엇을 문서화할지 결정하세요.¶

시작하기 전에 어떤 종류의 문서를 작성할 것인지 고려하세요: 튜토리얼인지, 참조 문서인지, 사용 설명서인지, 설명서인지?

제품의 특성이 작성해야 할 문서 유형에 직접적인 영향을 미친다는 점을 명심하세요.

프레임워크를 만드세요.¶

먼저 문서의 기초를 구축하세요. 처음에는 매우 작은 것일 수 있으며, 몇 개의 그룹만 포함할 수 있지만, 시간이 지남에 따라 구축 중인 전체 플랫폼이 크기와 복잡성이 증가하기 시작할 것입니다. 조직 구조를 정기적으로 검토해야 합니다.

여러분은 교사이고, 학생들이 수업에서 어떻게 배우는지에 대한 최종 책임이 있다는 점을 기억하세요. 학생들은 여러분의 지시를 따를 것입니다. 따라서 구조에 더 많은 시간을 투자할수록 학생들은 더 성공적으로 배울 것입니다.

항상 멀티미디어 기술을 활용하세요.¶

비디오, 그림, 다양한 스타일을 활용하고 문서에 직접 삽입하세요. Docsie는 이 과정을 쉽게 만들기 위해 플랫폼 내에 이러한 요소들을 임베딩할 수 있게 해줍니다.

이러한 요소들은 소비자가 전달하려는 정보를 더 잘 이해하는 데 도움이 될 뿐만 아니라, 동적 문서화의 결과로 더 많은 고품질 리드로 이어지는 훌륭한 검색 엔진 최적화(SEO)도 제공합니다.

검색 가능한지 확인하세요.¶

다양한 지식 베이스 플랫폼의 검색 기능에는 차이가 있습니다. 일부는 세분화된 기능이 없는 기본 검색만 제공하고(파일이 수천 개가 아니라면 기술적으로 괜찮습니다), 다른 일부는 문서뿐만 아니라 사용자 이름에서도 검색할 수 있는 쿼리 옵션을 제공합니다.

그러나 한 가지 중요한 점은 빠르게 검색할 수 있는 도구를 사용해야 한다는 것입니다. 앱 내에 포함된 검색 기능을 사용하면 앱을 떠나지 않고도 파일을 쉽게 검색하고 미리 볼 수 있습니다.

Docsie는 정보에 쉽게 접근할 수 있는 동적으로 검색 가능한 탐색 기능을 제공합니다.

지속적으로 개선하고 업데이트하세요¶

문서를 만들고 사용하는 것은 어렵습니다. 문서는 그것을 만들거나 혜택을 받은 사람들에 의해 빠르게 잊혀지기 때문입니다. 문서는 또한 여정에서 여러 도전과제에 직면합니다.

시간이 지남에 따라 폴더 구조는 묘지처럼 보이게 됩니다. 오래된 문서는 화면 아래쪽에 남아있는 경향이 있기 때문입니다.

그러니 오래된 문서를 다시 확인하고 개선하며, 동료들도 때때로 같은 일을 하도록 장려하세요. Docsie는 고급 버전 관리 시스템을 통해 간단하고 쉽게 업데이트를 만들 수 있게 해줍니다.

마치며:¶

효과적인 문서 작성 방법에 대해 더 알고 싶으신가요? 소프트웨어 문서 전문가를 위한 많은 블로그와 정보를 여기에서 찾아볼 수 있습니다.