오픈 소스 프로젝트의 모래반 : 문서화

튜토리얼

당신이 자신의 관심사와 완벽하게 부합하는 오픈 소스 프로젝트를 우연히 발견했다고 상상해보십시오. 당신은 그것을 사용하거나 기여하려고 열정적이지만, 어디서 시작해야 할까요? 해답은 그 프로젝트의 문서에 있습니다.

이제 오픈 소스 문서를 프로젝트에서 최대한 이용할 수 있도록 안내하는 가이드로 생각해보세요. 이 문서는 사용자를 프로젝트의 복잡성을 안내하면서도 프로젝트의 핵심 원칙, 사용 방법 및 기여 방법을 이해하는 데 도움을 줍니다.

이 기사에서는 오픈 소스 문서, 오픈 소스 문서의 종류, 중요성에 대해 논의하고, 만드는 데 가장 좋은 방법 및 오픈 소스 문서를 작성하는 프로세스를 간소화하는 도구에 대해 살펴볼 것입니다.

가장 먼저 “오픈 소스”를 정의해 봅시다. 오픈 소스란 간단히 말해, 소스 코드가 대중에게 공개되어 검토, 수정, 향상 및 배포할 수 있는 유형의 소프트웨어를 의미합니다. 예를 들어, Linux 운영 체제, Firefox 웹 브라우저, MongoDB 등이 있습니다.

이제, 오픈 소스 문서는 오픈 소스 소프트웨어와 관련된 문서 자료를 가리킵니다. 제품의 사용, 기능 및 유지 관리에 대한 정보를 제공합니다. 이 문서에는 소프트웨어의 기능, 설치 구성 및 사용에 대한 세부 정보가 포함되어 있습니다. 이 문서는 일반적으로 소스 코드와 함께 대중에게 제공됩니다.

오픈 소스 문서는 개발자, 사용자 및 기여자에게 포괄적인 자료로서 프로젝트의 목적, 기능 및 사용에 대한 필수 정보를 제공합니다. 처음에는 오픈 소스 프로젝트가 압도적으로 느껴질 수 있지만, 좋은 문서의 도움으로 사용자와 기여자는 프로젝트를 이해할 수 있습니다.

오픈 소스 프로젝트는 일반적으로 3가지 유형의 문서를 가지고 있습니다. 각 문서는 특정 요구를 충족합니다. 여기에는 기술 문서, 제품 문서 및 가이드라인이 포함됩니다.

기술 문서 : 이 문서는 개발자를 위한 것입니다. 코드 베이스에 깊이 파고들고, API를 설명하며, 프로젝트의 프로그래밍 인터페이스를 사용하는 방법을 시연합니다. 또한 프로젝트에 대한 소개 문서, 프로젝트와 함께 작업하는 개발자를 위한 가이드라인, 개발 환경 구성에 대한 지침을 포함합니다. API 문서, 개발 가이드 및 README는 훌륭한 기술 문서의 예입니다.

제품 문서 : 이 문서는 프로젝트의 사용자들을 대상으로 합니다. 사용자 설명서, 빠른 시작 가이드, 설치 가이드, 문제 해결 가이드, FAQ 등이 포함됩니다. 이들은 본질적으로 사용자의 경험에 초점을 맞추고 사용자가 프로젝트, 기능 및 프로젝트 사용 방법을 이해하도록 안내합니다.

가이드라인 : 이 문서는 프로젝트의 기여자를 위해 맞춤화되어 있습니다. 이들은 기여자가 프로젝트를 탐색하는 방법을 이해하는 데 도움을 줍니다. 일반적인 오픈 소스 프로젝트 가이드라인의 유형은 다음과 같습니다:

  1. 기여 가이드 : 프로젝트에 기여하는 방법, 코드 제출 및 버그 보고/수정 등을 설명하므로 매우 중요합니다.

  2. 스타일 가이드: 선호되는 스타일, 형식 및 명명 규칙에 대한 정보를 제공합니다. 이는 코드 및 기여의 품질과 일관성을 보장합니다.

  3. 행동 강령 : 기여자와 커뮤니티 구성원에게 기대되는 행동을 제공합니다.

좋은 문서는 프로젝트 사용자나 기여자 모두에게 매우 중요합니다. 좋은 문서가 오픈 소스 프로젝트의 사용자와 기여자에게 어떻게 도움이 되는지 살펴보겠습니다.

사용자를 위한:

  1. 향상된 사용자 경험 : 좋은 문서는 사용자가 프로젝트를 효과적으로 활용하고 최대한 활용하는 방법을 이해하는 데 도움을 줍니다. 이는 사용자가 프로젝트를 사용할 때 직면할 수 있는 문제에 대한 더 빠른 해결책을 제공합니다.

  2. 소프트웨어의 쉬운 채택과 사용: 명확하고 간결한 문서 작성은 소프트웨어의 기능과 기능을 이해하는 데 도움이 됩니다. 학습 곡선을 줄이고 소프트웨어를 보다 넓은 범위의 사용자에게 접근 가능하게 만듭니다.

  3. 문제 해결: 상세한 문서 작성은 사용자가 문제 해결에 도움을 받고 독립적으로 해결책을 찾는 데 도움이 될 수 있습니다. 이는 지원 인력에 대한 의존을 줄이고 전체 사용자 경험을 향상시킵니다.

  4. 지원 비용 절감: 좋은 문서 작성은 지원 문의 수를 최소화하고 사용자와 개발자 모두에게 시간과 자원을 절약하는 데 도움이 될 수 있습니다.

기여자를 위한:

  1. 프로젝트에 대한 명확한 이해 : 프로젝트에 기여하려면 프로젝트를 이해해야 합니다. 좋은 문서화는 독자가 프로젝트를 이해하고 기여를 시작하는 방법을 이해하는 데 도움이 됩니다.

  2. 효과적인 온보딩 : 좋은 문서화는 기여자들에게 원활한 온보딩 프로세스를 제공합니다. 이는 기여자들이 프로젝트의 코드베이스, 작업 흐름 및 기여를 위해 필요한 세부 정보에 더 익숙해지도록 돕습니다.

  3. 향상된 협업: 명확하고 간결한 문서화는 기여자들을 위한 공통 기반을 만들어줍니다. 이는 모든 사람이 프로젝트의 목표, 아키텍처 및 코딩 규칙을 이해하는 것을 보장합니다. 기여자들은 자신의 작업을 수행하는 데 필요한 정보를 쉽게 얻을 수 있어 지연과 오해를 줄일 수 있습니다.

좋은 문서 작성을 위한 모범 사례

지금까지 논의한 것에서 보듯이 오픈 소스 프로젝트를 위해 좋은 문서를 작성하는 것이 정말 중요하다는 것을 알 수 있습니다. 사용자 및 프로젝트 기여자들의 요구를 충족시킬 수 있는 좋은 문서를 작성하기 위해 다음 몇 가지 작업을 수행해야 합니다.

  1. 독자가 쉽게 이해할 수 있도록 명확하고 간결하게 작성하세요. 문서의 본질은 사용자 경험을 향상시키는 것이므로 독자를 혼란스럽게 할 수 있는 복잡한 기술 용어의 사용을 피하는 것이 중요합니다

  1. 문서를 구조화된 방식과 패턴으로 구성하세요. 이를 달성하기 위해서는 제목, 소제목 및 글머리 기호를 사용하여 정보를 논리적으로 배열해야 합니다. 문서는 구조화된 패턴을 따라야 하며 모든 것이 위에서 아래로 잘 흐르며 독자가 쉽게 따라갈 수 있어야 합니다

  2. 사용자의 요구를 고려하여 작성하십시오. 사용자의 입장에 서서 문서화는 도움이 되는 자원이어야 합니다. 개념을 가능한 명확하게 설명하십시오. 상식을 가정하지 마십시오. 특정 개념을 설명하는 데 코드 조각을 포함하거나 일반적인 질문을 예상하고 직접적인 해결책/답변을 제공할 수 있습니다.

  3. 프로젝트에 변경이 있을 때 문서를 최신 상태로 유지하십시오. 변경 사항이 발생할 때마다 문서를 업데이트하십시오. 코드와 함께 문서를 제공해야 합니다. 코드 기반이 업데이트되는 동안 문서도 업데이트되어야 합니다.

  4. 프로젝트에 기여하는 방법에 대한 명확한 지침을 제공하십시오. 이렇게 하면 기여하려는 사람들이 프로젝트를 탐색하고 변경 사항을 쉽게 만들 수 있습니다.

  5. 오류, 불일치 또는 오래된 정보를 확인하십시오. 또한 사용자로부터 피드백을 요청하여 문서를 개선하는 데 도움이됩니다.

  6. 마지막으로는 좋은 문서를 작성하는 데 도움이되는 도구를 활용하는 것이 좋습니다. 여러 도구를 활용할 수 있습니다.

좋은 문서 작성을 위한 도구

이전에 언급했듯이, 사용자가 쉽게 살펴보고 이해할 수있는 좋은 문서를 만들기 위해 활용할 수있는 도구가 많이 있습니다. 여기에 몇 가지가 있습니다.

  1. 스핑크스 : 특히 파이썬 프로젝트에 대한 기술 문서를 작성하는 데 인기있는 도구입니다. 다양한 출력 형식 (HTML, PDF, LaTeX)을 지원하며 다양한 확장 기능이 풍부합니다.

  2. Doxygen : 소스 코드 주석에서 API 문서를 생성하는 도구입니다. 다양한 프로그래밍 언어를 지원하며 HTML, LaTeX 및 기타 형식으로 문서를 생성할 수 있습니다.

  3. MkDocs: 콘텐츠 작성을 위해 Markdown을 사용하는 간단하고 빠르며 구성 가능한 문서 생성기입니다. 소규모 프로젝트에 적합합니다.

  4. Read the Docs: Sphinx 또는 MkDocs로 작성된 문서를 위한 호스팅 플랫폼입니다. 소프트웨어 문서를 빌드, 버전 관리 및 호스팅하여 간소화합니다.

  5. Git : Git은 시간에 따라 문서의 변경 사항을 추적할 수 있게 해줍니다. 이는 필요할 경우 이전 버전으로 쉽게 되돌릴 수 있다는 것을 의미하며, 우연한 삭제를 방지하는 데도 도움이 됩니다. 문서의 지속적인 업데이트에 도움이 됩니다.

각 도구의 문서를 살펴보면 그들이 어떻게 작동하는지, 그리고 사용하는 방법에 대한 깊이 있는 이해를 얻을 수 있습니다.

결론

결론적으로, 좋은 문서는 프로젝트가 얼마나 잘 이해되고 활용되는지를 결정합니다. 오픈 소스 프로젝트를 사용하려는 모든 사람의 요구를 충족하는 명확하고 간결한 문서를 갖는 것이 필수적입니다.

이 기사에서 볼 수 있듯이, 철저하고 잘 구조화된 접근 가능한 문서를 만드는 데 시간과 노력을 투자함으로써 사용자 경험을 개선할 뿐만 아니라 프로젝트의 지속 가능성을 보장할 수 있습니다.

다음에 주목할만한 오픈 소스 프로젝트를 만나게 되면, 깊이 파고들기를 두려워하지 마세요; 문서는 프로젝트를 사용하거나 기여하는 데 도움이 되는 안내서가 될 것입니다.

자료

https://opensource.googleblog.com/2018/10/building-great-open-source-documentation.html

https://opensource.com/article/20/3/documentation

https://herothemes.com/blog/best-documentation-tools/

Source:
https://dherrbie.hashnode.dev/the-corner-stone-of-open-source-project-its-documentation