라이브러리 작성자가 유용한 문서를 작성하기 위한 모범 사례

라이브러리에 제공하는 문서는 매우 중요합니다. 문서는 사용자가 라이브러리를 탐색하고, 프로젝트에 채택하고, 어려움에 부딪혔을 때 포기하지 않고 지속할지 여부를 결정할 수 있습니다. 오늘날 개발자들은 언어, 라이브러리, 프레임워크 및 플랫폼 간에 전례 없는 선택권을 가지고 있습니다. 따라서 사용자들의 참여를 유도하고 정보를 제공하는 것이 필수적입니다. 그렇지 않으면 그들은 다른 대안을 찾을 수 있습니다.

라이브러리의 초기 버전에서는 사용자로부터의 피드백이 드뭅니다. 다행히도 문서를 작성하고 개선하는 것은 프로젝트의 품질을 크게 향상시키는 피드백 루프 역할을 할 수 있습니다. 따라서 문서 작성은 결코 부담으로 여겨져서는 안 되며, 라이브러리를 만들 때 우선순위에서 밀려나서도 안 됩니다.

효과적인 문서는 사용자에게 정보를 제공할 뿐만 아니라 라이브러리의 개발 및 개선을 주도합니다. 다음은 문서가 개발 프로세스를 안내할 수 있는 몇 가지 핵심 방법입니다.

• 몇 단락으로 라이브러리가 무엇을 하는지, 누가 사용함으로써 이점을 얻을지, 그리고 대안적인 접근 방식에 비해 어떤 장점이 있는지 설명할 수 있어야 합니다. 만약 이를 할 수 없다면, 프로젝트의 범위와 목표를 재고해 보세요.
• 잠재 사용자가 가능한 한 빨리 시작하고 실행할 수 있도록 "시작하기(Getting Started)" 가이드를 만들 수 있어야 합니다. 빠르게라는 기준은 문제 도메인에 따라 달라지겠지만, 다른 플랫폼의 유사한 라이브러리와 비교해 볼 수 있습니다. 이 가이드는 사용자를 피드백 루프에 참여시켜 계속해서 더 쉽고 빨라지면서도 항상 신뢰할 수 있는 결과를 생성하도록 해야 합니다. 이 가이드를 작성하는 것은 사용자의 진행을 방해할 수 있는 복잡성의 급격한 증가(절벽)를 식별하는 데 도움이 될 것입니다.
• 함수를 문서화하는 행위는 유효한 입력 범위, 발생할 수 있는 예외, 작업량이 증가함에 따라 성능이 어떻게 저하되는지 등 모든 엣지 케이스를 고려하도록 강제합니다. 이는 종종 함수 시그니처와 기본 구현의 개선으로 이어질 수 있습니다.
• 라이브러리를 초기화하는 데 필요한 코드가 작업을 완료하는 데 필요한 코드를 항상 넘어선다면, 구성 옵션을 다시 생각해보세요.
• 표준 옵션을 사용하여 기본 작업을 수행하는 명확한 예제를 만들 수 없다면, 일상적인 사용을 위해 API를 최적화하는 것을 고려해 보세요.
• 실제 데이터 소스나 온라인 서비스를 사용하지 않고 라이브러리를 테스트하는 방법을 시연할 수 없다면, 네트워크(및 일반적으로 외부 세계)에 접근하는 컴포넌트를 위한 테스트 더블(test doubles)을 제공하는 것을 고려해 보세요.

라이브러리에 대한 문서를 빨리 제공할수록 실제 사용자들에 의해 더 빨리 테스트될 수 있습니다. 이러한 테스트에서 얻은 피드백은 디자인을 개선하는 데 사용될 수 있습니다.

포괄적인 문서 제공

사용자가 최소한의 노력으로 라이브러리를 채택할 수 있도록 충분한 문서를 제공해야 합니다. 이 문서에는 다음이 포함되어야 합니다.

• 시작하기 가이드
• API에 대한 심층 설명
• 일반적인 사용 사례(레시피라고도 함)에 대한 더 긴 예제
• 블로그, 기사, 웨비나, 컨퍼런스 강연과 같은 리소스 링크

시작하기 가이드는 라이브러리가 지원되는 빌드 시스템과 어떻게 통합되는지 다루어야 합니다. 가장 일반적으로 사용되는 엔티티에 대한 간략한 설명과 사용 방법에 대한 작은 예제가 포함되어야 합니다. 라이브러리가 외부 세계와 상호작용하는 각 지점에서는 환경을 구성하는 데 필요한 단계와 이러한 단계가 성공적으로 완료되었는지 확인하는 방법을 명시해야 합니다. 필요한 단계가 없는 경우 명시적으로 기술하세요.

가능하다면 지원하는 라이브러리 버전별로 별도의 문서 버전을 제공하세요. 이렇게 하면 사용자가 오래되었거나 너무 최신 정보를 보는 것을 방지할 수 있습니다. 이것이 불가능할 경우, 재설계된 API 부분과 관련된 문서 섹션을 명확하게 표시하세요.

사용자를 위한 페르소나 생성

대상 독자에 대한 명확한 이해 없이 문서를 작성하고 평가하는 것은 어렵습니다. 문서를 읽을 사용자 유형에 대한 여러 페르소나를 정의하는 것이 도움이 될 수 있습니다.

사용자의 제약 조건, 예를 들어 작업해야 하는 기존 소프트웨어 스택과 같은 것들을 고려하세요. 문서 검토자들은 이러한 페르소나를 채택하여 결론을 더 의미 있게 만들 수 있습니다.

사용자에 대한 특정 정보가 부족할 때는 비관적으로 접근하는 것이 좋습니다. 예를 들어, Kotlin의 최신 또는 가장 고급 기능에 대한 전문 지식을 가정하지 마세요. 코드 예제는 가능한 한 간단하게 유지하세요.

페르소나는 시간, 예산 제약 또는 기밀 유지 계약으로 인해 실제 사용자와 상담할 수 없을 때 특히 유용합니다. 시간이 지남에 따라 사용자를 더 잘 이해하게 되면, 그들의 필요에 더 정확하게 맞춰 페르소나를 다듬으세요.

가능한 한 예제를 통해 문서화

예제를 통한 문서화는 사용자에게 기본 개념을 설명하는 가장 비용 효율적인 방법 중 하나입니다. 가능한 한, 현재 논의 중인 주제나 개념을 설명하거나 시연하는 데 도움이 되는 간단하고 명확한 코드 예제를 제공하세요.

KDoc 문서 형식은 문서 주석에서 Markdown을 사용한 인라인 마크업을 사용할 수 있도록 합니다. 주석 내의 인라인 코드 스니펫을 사용하여 API 사용법을 보여주세요. 예시를 보려면 코루틴 라이브러리의 테스트 디스패처에 대한 소스 코드 및 렌더링된 문서를 참조하세요.

이와 같은 예제를 제공하면 예상되는 입력, 가능한 출력 및 실패 모드에 대한 장황한 설명을 작성할 필요를 피할 수 있습니다. 그러나 각 예제의 맥락은 명확해야 하며, 관련성 있는 상황도 명확해야 합니다. 단순히 주석 없는 샘플 프로그램 폴더를 제공하는 것은 문서로 간주되지 않습니다.

API를 철저히 문서화

지원되는 모든 API 진입점은 KDoc을 사용하여 문서화되어야 합니다.

Kotlin의 문서 엔진인 Dokka는 기본적으로 출력에 public 선언만 포함합니다. 단순성 섹션에서 논의되었듯이, public API를 최소화하고 사용자가 접근하지 않기를 원하는 public 진입점을 제거해야 합니다. 가시성을 제어하여 사용자로부터 숨길 수 없는 API가 있다면, suppress 지시문을 사용하여 문서에서 제외하세요.

진입점 설명은 함수가 수행하는 작업에 대한 명확하고 상위 수준의 설명으로 시작하세요. 자연어로 단순히 시그니처를 다시 설명하는 것을 피하세요.

예를 들어, " String을 받아 Connection을 반환한다"고 말하는 대신, "입력 문자열로 지정된 데이터베이스에 연결을 시도하며, 성공하면 Connection을 반환하고, 그렇지 않으면 ConnectionTimeoutException을 발생시킨다"고 말할 수 있습니다.

각 입력의 예상 값과 다른 입력에 대한 동작을 지정하세요. 유효한 값의 범위와 유효하지 않은 값이 제공될 때 발생하는 상황을 설명하세요. 예를 들어, 문자열 입력이 URL이어야 하는 경우, 문자열이 비어 있거나, 유효하지 않거나, 지원되지 않는 프로토콜을 사용하거나, 존재하지 않는 위치를 참조하는 경우에 어떤 일이 발생하는지 설명하세요.

API 진입점이 발생시킬 수 있는 모든 예외를 문서화하세요. 실패 조건은 일반적인 설명에서 논의하고 예외 섹션은 상세 정보를 위해 남겨두세요. 이렇게 하면 가독성이 높아지고 독자가 집중하는 데 도움이 됩니다. 대신, 이 정보를 일반 설명에 자연스럽게 포함하세요. 가능한 한 사용 예제를 제공하는 것도 사용자가 API를 올바르게 사용하는 방법을 이해하는 데 도움이 됩니다.

문서의 명확성과 효율성을 개선하기 위해 기술 문서 작성(technical writing)에 대해 배우는 것을 권장합니다. Google의 다음 코스와 같은 리소스를 탐색해 보세요. (1부 및 2부).

람다 매개변수 문서화

API 진입점이 람다를 취할 때, 사용자는 라이브러리가 자신을 대신하여 실행할 일부 기능을 제공하는 것입니다. 이는 최소한 두 가지 영역에서 추가 문서화를 필요로 합니다.

첫째, 람다가 예외를 발생시키면 어떻게 되는지 문서화하세요. 다음 질문에 대한 답변을 고려해 보세요.

• 즉시 실패를 유발하는가, 람다가 반복적으로 호출되는가, 아니면 대체 동작이 있는가?
• 호출 함수가 종료되어야 한다면, 람다에서 발생한 예외를 다시 던지는가 아니면 다른 예외를 던지는가?
• 예외가 다르다면, 원래 예외를 포함하는가?

또한, 함수가 inline으로 선언되지 않는 한, 동시성과 관련된 특별한 동작을 문서화하세요. 다음 사항이 다루어졌는지 확인하세요.

• 람다가 호출자와 동일한 스레드에서 호출되는가?
• 람다가 호출자와 동일한 스레드에서 호출되지 않는다면, 어떤 스레드(또는 스레드 풀)에서 호출되는가?
• 람다의 여러 복사본이 병렬로 실행될 수 있는가?
• 다른 어떤 작업이 해당 스레드를 사용할 수 있는가?
• 사용자가 라이브러리가 사용할 스레드를 지정할 수 있는가?
• 여러 람다가 호출될 때, 순서에 대해 어떤 보장이 제공되는가?

문서에 명시적인 링크 사용

API 진입점이 라이브러리의 다른 기능과 완전히 독립적인 경우는 매우 드뭅니다. 일반적으로 호출은 특정 순서로 이루어져야 하며, 특정 작업을 수행하는 여러 옵션이 있고, 관련 작업을 수행하는 진입점은 유사한 방식으로 사용됩니다. 예를 들어, format 및 parse 함수는 서로를 반영합니다.

@see 태그 또는 내부 링크를 사용하여 문서에 이러한 관계를 명시적으로 나타내세요. 이는 독자가 정보를 덩어리(chunk)로 묶어 이해하고, 라이브러리에 대한 더 잘 통합된 정신적 지도를 구축하는 데 도움을 줍니다.

가능한 한 자체 포함적으로 작성

입력이 유효한지 설명할 때, W3C, IEEE 또는 유니코드 컨소시엄에서 생산하는 것과 같은 관련 표준을 단순히 참조하고 싶은 유혹이 있습니다. 이러한 링크를 제공하는 것이 도움이 될 수 있지만, 독자가 공백 문자 집합과 같은 기본 정보를 찾기 위해 외부 사양을 참조하도록 강요받아서는 안 됩니다.

가능한 한 문서는 자체 포함적이어야 합니다. 사용자가 각 API 진입점의 일반적인 사용법을 이해하기에 충분한 정보를 제공해야 합니다. 일반적인 사용에서는 발생하지 않을 엣지 케이스에 대해서는 사용자에게 외부 문서를 참조하도록 안내할 수 있습니다.

쉬운 영어 사용

문서를 작성할 때는 간단하고 명확한 영어를 사용하는 것이 중요합니다. 이렇게 하면 영어가 모국어가 아닌 사람들을 포함하여 전 세계 사용자에게 콘텐츠가 접근 가능하도록 보장됩니다. 독자를 혼란시킬 수 있는 복잡한 단어, 전문 용어, 라틴어 구문 또는 관용적 표현 사용을 피하세요. 대신, 직관적인 언어와 간결한 문장을 사용하세요.

쉬운 영어는 필요한 경우 문서를 번역하기 더 쉽게 만듭니다. 명확하고 모호하지 않은 텍스트는 오해의 위험을 줄이고 전반적인 가독성을 향상시킵니다.

다음 단계

아직 확인하지 않았다면 다음 페이지를 확인해 보세요.

• 정신적 복잡성 최소화 페이지에서 정신적 복잡성을 최소화하기 위한 전략을 살펴보세요.
• 하위 호환성 페이지에서 하위 호환성 유지에 대해 알아보세요.