기술적 전문 지식 없이도 제품 문서화 프로세스를 간소화하고 싶으신가요? Apidog는 제품 관리자와 운영 팀이 전문적인 문서를 원활하게 생성, 관리 및 게시할 수 있도록 지원하는 포괄적인 솔루션을 제공합니다. 직관적인 인터페이스, 실시간 협업 기능, 그리고 무유지보수 게시 기능을 통해 Apidog는 팀이 문서화 워크플로우에 접근하는 방식을 혁신합니다.
모든 제품은 자체적인 문서가 필요합니다. 제품이 매우 직관적이고 간단한 상호 작용 디자인을 가진 소비자용 애플리케이션이라 할지라도, 더 많은 설명이 필요한 영역이 있을 것이며, 이는 제품 인터페이스에 직접 제시될 경우 복잡성을 더할 수 있습니다. 따라서 문서 관리, 유지보수 및 게시는 모든 제품에 있어 중요한 관심사입니다.
제품 문서를 구축할 때 팀은 일반적으로 Notion과 같은 즉시 사용 가능한 문서화 도구, Confluence 및 CMS와 같은 콘텐츠 관리 도구, 또는 Docusaurus 및 Gitbook과 같은 문서 생성기를 사용합니다. 그러나 이러한 솔루션은 종종 다음과 같은 문제에 직면합니다:
- 문서 작성을 위해 코딩이 필요하며, 비용이 많이 듭니다. 문서가 작성된 후에도 실제 읽기 경험은 종종 기대에 미치지 못합니다.
- 문서 작업에는 여러 역할이 협업해야 하며, 버전 관리가 어렵고 최적화 제안을 다른 사람에게 전달하기 어렵습니다.
- 완성된 문서를 프로덕션 환경에 게시하는 것이 너무 간단하거나 너무 복잡하여, 비기술 직원이 다루기 어려운 엔지니어링 프로세스가 포함될 수 있으며, 오류로 이어질 수 있습니다.
Apidog 팀은 이전에 Docusaurus를 사용하여 문서를 만들었습니다. 문서가 계속해서 반복되면서, 위에서 언급한 문제들 중 일부에 직면했습니다. 경험과 교훈을 요약한 후, 우리는 솔루션을 개발하고 이를 Apidog에 통합했습니다. 이제 Apidog 팀의 제품 문서는 Apidog로 완전히 마이그레이션되었으며, 모든 생성 및 표시는 Apidog에서 처리됩니다.
Apidog를 통해 제품 문서를 구축하는 방법에 대한 우리의 실제 사례를 공유하겠습니다. 그 전에, Apidog의 제품 문서의 구체적인 효과를 더 자세히 살펴보고 싶다면, Apidog 도움말 문서를 확인해 보세요. 피드백은 언제나 환영합니다.
배경
우리의 실제 사례를 소개하기 전에, 우리가 왜 이런 방식으로 일을 하는지 모두가 더 잘 이해할 수 있도록 먼저 설명해야 할 몇 가지 배경이 있습니다. 우리 회사의 제품 문서는 일반적으로 제품 및 운영 부서 동료들이 협력하여 작성합니다. 주요 프로세스는 다음과 같습니다:
위 프로세스에는 기술 인력의 개입이 필요 없습니다. 모든 제품 문서 관련 작업은 이 두 부서의 동료들이 완료합니다. 다음으로, 이 프로세스에 따라 Apidog를 통해 제품 문서 구축 작업을 완료하는 방법을 설명하겠습니다.
핵심 프로세스
1. 콘텐츠 관리 및 협업을 위한 스프린트 브랜치 생성
개발 이터레이션이 시작되면, 운영 동료들은 Apidog에 이터레이션 브랜치를 생성하여 현재 이터레이션에서 변경되는 모든 문서를 이 브랜치 안에 배치하여 협업하고, 메인 브랜치에 직접적인 영향을 미 미치지 않도록 합니다.
생성 후, 제품 관리자는 이터레이션에서 실제로 업데이트된 기능을 기반으로 수정이 필요한 기존 문서를 이 이터레이션 브랜치로 가져오고, 새로운 기능에 대한 새 문서를 이터레이션 브랜치에 직접 생성합니다. 여기에서의 작업은 API 문서의 이터레이션 브랜치 사용법과 완전히 일치합니다.
메인 브랜치에 보호를 설정했기 때문에, 메인 브랜치에서 문서 내용을 직접 변경하는 것은 허용되지 않습니다. 이는 사용자가 직접 볼 수 있는 게시된 문서의 내용을 수동으로 수정할 수 없다는 의미이며, 제품 문서를 더 안정적으로 만들고 임의의 변경으로 인해 잘못된 내용이 사용자에게 표시되는 상황을 줄여줍니다.
2. 아름다운 마크다운 에디터를 사용하여 각 문서 작성
제품 관리자는 이터레이션 브랜치 내에서 현재 이터레이션에 업데이트해야 하는 문서를 마크다운으로 작성합니다. Apidog의 마크다운 기능은 매우 강력하며, 다양한 시각적 구성 요소를 클릭하여 많은 복잡한 스타일을 낮은 진입 장벽으로 삽입할 수 있어, 추가 노력 없이도 아름다운 문서를 쉽게 작성할 수 있습니다.
일반적인 MD 스타일 시각적 삽입 외에도, Apidog는 다음과 같은 특별한 기능을 추가했습니다:
- 프로젝트 API/문서 삽입을 통해 문서들이 참조 체인을 형성하며 서로 연결되어 원활한 탐색을 제공하고, 독자들에게 더 부드러운 경험을 제공하며 독자의 요구 사항과 문제를 더 잘 해결합니다. 이는 매우 중요한 기능입니다.
- 아이콘, 하이라이트 블록, 테이블, 단계, Mermaid, 비디오 등 풍부한 리소스 삽입 기능을 제공하여, 문서를 더 보기 좋게 만들기 위해 직접 리소스를 찾거나 MD 스타일 문법을 배우는 데 시간을 낭비할 필요가 없습니다.
3. 제품/운영 동료들이 협력하여 문서 다듬기
제품 관리자가 이터레이션 브랜치에 문서의 초기 버전을 작성한 후, 문서의 품질, 명확성 및 사용자 유용성을 향상시키기 위해 문서를 운영 동료에게 넘겨 사용자 관점에서 읽고 다듬기 위한 수정 제안을 제공합니다.
이것은 예전에는 가장 시간이 많이 걸리고 힘든 부분이었습니다. 양측의 상호 협력이 필요했고, 한쪽은 자신의 아이디어를 설명하고 특정 부분에 대한 구체적인 수정 제안을 제공하며, 다른 한쪽은 이를 받아들이고 이해하며 실제로 변경했습니다. 왔다 갔다 하는 과정에서 오해, 잘못된 변경, 문서 버전 간의 내용 불일치 등 다양한 문제가 자주 발생하여 효율성이 매우 낮았습니다.
이제 Apidog를 사용하면 양측이 문서에서 직접 수정할 수 있으며, 변경 사항이 발생하면 실시간 메시지 알림이 IM으로 푸시되어 다른 사람들이 즉시 문서에 접속하여 특정 변경 사항을 쉽게 볼 수 있어 협업 효율성이 크게 향상됩니다. 구체적인 단계는 다음과 같습니다:
- 제품 관리자가 문서의 초기 버전을 만듭니다. 운영 담당자가 알림을 본 후 문서를 읽고 이 문서 내에서 변경하고 싶은 내용을 직접 수정합니다.
- 수정 사항은 저장 시 자동으로 알림을 트리거하여, 미리 구성된 IM 그룹에 변경 메시지 카드를 보냅니다. 그룹 구성원은 변경 개요 메시지 카드를 본 후 알림 링크를 클릭하여 관련 문서로 한 번의 클릭으로 진입할 수 있습니다.
- 수정 기록을 통해 현재 버전과 원본 버전을 선택하여 차이점을 비교함으로써 상대방의 수정 사항을 쉽게 확인하고 문서를 조정하는 방법을 결정할 수 있습니다. 제안을 수락하지 않고 원본 버전으로 복원하거나, 수정을 수락하고 최신 버전을 유지할 수 있습니다.
제품 및 운영 팀은 문서 내용이 다듬어지고 모두가 승인하는 버전이 결정될 때까지 위의 단계를 반복합니다.
4. 공식 문서 게시 전 준비 및 검토
문서의 내용과 제품 스크린샷이 사용자가 접근할 수 있는 것과 완전히 일치하도록 보장하기 위해, 제품의 프로덕션 환경에서 스크린샷을 찍는 것을 권장합니다. 이는 또한 프로덕션 환경에 출시된 새로운 기능이 제대로 작동하는지 확인할 수 있게 합니다. 운영 담당자가 온라인에서 새로운 기능을 사용하고 스크린샷을 찍은 후, 이를 문서에 추가합니다.
운영팀은 이번 이터레이션에서 완료된 콘텐츠 문서를 확인하고 선택한 후, 메인 브랜치로 병합하기 위한 MR 요청을 제출합니다.
운영 관리자 또는 기타 프로젝트 관리자는 게시될 문서 내용을 검토하고, 정확한지 확인한 후, 메인 브랜치로 병합을 선택합니다.
병합이 완료되면, 사용자가 게시된 문서에 접근할 때 메인 브랜치에 병합된 최신 내용을 볼 수 있습니다.
기타 장점
이미 소개된 기능 외에도, Apidog는 문서를 게시하는 측면에서 모든 사람이 필요에 더 잘 맞는 제품 문서 사이트를 구축할 수 있도록 다음과 같은 기능을 제공합니다.
1. 제품/회사 스타일에 맞는 전체 문서 사이트 스타일 설정
게시된 문서 사이트의 전체 스타일을 설정하여, 웹사이트 전체의 스타일이 회사의 톤과 더 잘 일치하도록 만들고, 더 많은 관련 리소스 및 회사 콘텐츠 링크를 추가하여 사용자에게 더 나은 경험을 제공할 수 있습니다.
Apidog의 도움말 문서는 자체 로고와 Apidog 관련 리소스 링크를 설정했습니다. 왼쪽 상단에는 회사 로고가 있고, 오른쪽 상단에는 다양한 회사 관련 리소스 링크가 있으며, 개발자들이 더 중요하게 생각하는 공개 API 문서도 제품 문서 내에 설정되어 있습니다:
2. 무유지보수 게시 경험
Apidog에서는 문서 게시 기능에서 "게시" 버튼만 클릭하면 전체 문서를 인터넷에 한 번의 클릭으로 게시하여 사용자가 읽을 수 있도록 할 수 있습니다. Apidog는 모든 사람이 사용할 수 있도록 공식적으로 도메인을 제공하여 많은 유지보수 작업을 절약합니다.
물론, 문서가 회사 웹사이트와 더 비슷하게 보이도록 해야 한다면, 사용자 지정 도메인 기능도 제공하여 회사 자체 도메인을 사용하여 문서에 접근할 수 있습니다.
또한, 게시된 제품 문서 사이트에서 일반 검색, Algolia 전체 텍스트 검색, GA 통합, 리디렉션 설정 및 기타 고급 기능을 간단한 조작으로 쉽게 설정할 수 있습니다. 이러한 구성은 운영자가 충분한 엔지니어링 능력을 가질 필요 없이 인터페이스 안내 및 도움말 문서를 따라 쉽게 설정할 수 있습니다.
3. 다양한 SEO 친화적 설정
Apidog는 기본 설정을 기반으로 게시된 문서 사이트에 합리적인 슬러그를 자동으로 생성하여 사용자가 더 잘 접근하고 공유할 수 있도록 합니다.
물론, 더 고급 SEO 요구 사항이 있다면, 각 개별 문서에 대한 사용자 지정 슬러그, 메타 데이터 및 기타 다양한 콘텐츠 설정도 지원합니다.
결론
위 내용은 Apidog를 활용한 제품 문서 유지보수의 구체적인 실제 사례입니다.
위에 언급된 내용 외에도, 제품 도움말 문서, 개발자 문서 및 API 문서를 하나의 스타일로 유지하고 모두 연결하여 더욱 향상된 사용자 경험을 제공할 수 있습니다. 실제 상황이 적합하다면, 이 실제 사례를 시도해보고 다른 동료들에게도 추천해 주십시오. 이것이 귀사의 제품 문서 구축 작업에 효율성과 품질 향상을 가져다주기를 바랍니다.