라이브러리 작성자가 유익한 문서를 작성하기 위한 권장 사항

라이브러리와 함께 제공되는 문서는 매우 중요합니다. 사용자가 라이브러리를 살펴볼지, 프로젝트에 도입할지, 그리고 어려움에 부딪혔을 때 이를 계속 사용할지 여부를 결정짓는 핵심 요소가 될 수 있습니다. 오늘날 개발자들은 언어, 라이브러리, 프레임워크, 플랫폼 등 전례 없이 다양한 선택지를 가지고 있습니다. 따라서 사용자의 관심을 끌고 정보를 제공하는 것이 필수적입니다. 그렇지 않으면 사용자는 다른 대안을 찾아 떠날 수 있습니다.

라이브러리의 초기 버전에서는 사용자 피드백이 부족할 수 있습니다. 다행히도 문서를 작성하고 다듬는 과정 자체가 피드백 루프 역할을 하여 프로젝트의 품질을 크게 높일 수 있습니다. 그러므로 문서 작성은 결코 부담스러운 짐으로 여겨져서는 안 되며, 라이브러리를 만들 때 우선순위에서 밀려나서도 안 됩니다.

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

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

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

포괄적인 문서 제공

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

• 시작 가이드(Getting Started guide)
• API에 대한 심층적인 설명
• 일반적인 사용 사례에 대한 긴 예시(레시피라고도 함)
• 블로그, 아티클, 웨비나, 컨퍼런스 발표 등 관련 리소스 링크

시작 가이드는 라이브러리가 지원되는 빌드 시스템과 어떻게 통합되는지 다루어야 합니다. 가장 자주 사용되는 엔티티(entity)에 대한 간략한 설명과 함께 작은 사용 예시가 포함되어야 합니다. 라이브러리가 외부 세계와 상호작용하는 모든 지점에서 환경을 구성하는 데 필요한 단계와, 이러한 단계가 성공적으로 완료되었는지 확인하는 방법을 명시하십시오. 별도의 단계가 필요하지 않다면 이를 명확히 밝히십시오.

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

사용자 페르소나 생성

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

사용자가 작업해야 하는 기존 소프트웨어 스택과 같은 제약 사항을 고려하십시오. 문서 검토자는 이러한 페르소나를 채택하여 결론을 더 의미 있게 도출할 수 있습니다.

사용자에 대한 구체적인 정보가 부족할 때는 보수적으로(pessimistic) 생각하는 것이 가장 좋습니다. 예를 들어, 사용자가 Kotlin의 최신 기능이나 고급 기능에 능숙하다고 가정하지 마십시오. 코드 예제는 가능한 한 단순하게 유지하십시오.

페르소나는 시간, 예산 제약 또는 기밀 유지 계약으로 인해 실제 사용자와 상담할 수 없을 때 특히 유용합니다. 시간이 지나면서 사용자에 대한 이해도가 높아지면, 페르소나를 수정하여 그들의 요구사항을 더 정확하게 반영하십시오.

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

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

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

이와 같은 예제를 제공하면 예상 입력, 가능한 출력 및 실패 모드에 대한 긴 설명을 쓸 필요가 없습니다. 하지만 각 예제의 맥락과 해당 예제가 관련 있는 상황이 명확해야 합니다. 단순히 주석이 없는 샘플 프로그램 폴더를 제공하는 것만으로는 문서라고 할 수 없습니다.

API를 철저하게 문서화

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

Kotlin의 문서 생성 엔진인 Dokka는 기본적으로 public 선언만 결과물에 포함합니다. 단순성(Simplicity) 섹션에서 논의했듯이, 공개 API를 최소화하고 사용자가 접근하지 않기를 바라는 공개 진입점은 제거해야 합니다. 가시성을 제어하여 사용자로부터 숨길 수 없는 API가 있다면, suppress 지시어를 사용하여 문서에서 제외하십시오.

진입점에 대한 설명은 해당 함수가 수행하는 작업에 대한 명확하고 수준 높은 설명으로 시작하십시오. 단순히 시그니처를 자연어로 다시 서술하는 것은 피하십시오.

예를 들어, “String을 받아서 Connection을 반환한다”라고 하지 말고, “입력 문자열로 지정된 데이터베이스에 연결을 시도하며, 성공하면 Connection을 반환하고 실패하면 ConnectionTimeoutException을 발생시킨다”와 같이 작성하십시오.

각 입력의 예상 값과 서로 다른 입력에 따른 동작을 명시하십시오. 유효한 값의 범위와 잘못된 값이 제공되었을 때 어떤 일이 발생하는지 설명하십시오. 예를 들어, 문자열 입력이 URL이어야 하는 경우 문자열이 비어 있거나, 유효하지 않거나, 지원되지 않는 프로토콜을 사용하거나, 존재하지 않는 위치를 참조할 때 어떤 일이 발생하는지 기술하십시오.

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

문서의 명확성과 효과를 높이기 위해 기술 글쓰기(Technical Writing)에 대해 배우는 것을 권장합니다. Google에서 제공하는 교육 과정(1부 및 2부)과 같은 리소스를 살펴보는 것을 고려해 보십시오.

람다 파라미터 문서화

API 진입점이 람다를 받는다는 것은 사용자가 라이브러리가 대신 실행할 기능을 제공한다는 의미입니다. 여기에는 최소 두 가지 영역에서 추가적인 문서화가 필요합니다.

첫째, 람다가 예외를 발생시킬 때 어떤 일이 발생하는지 문서화하십시오. 다음 질문들에 대한 답을 고려해 보십시오.

• 즉각적인 실패를 일으키나요, 람다가 반복적으로 호출되나요, 아니면 폴백(fallback) 동작이 있나요?
• 호출하는 함수가 종료되어야 하는 경우, 람다에서 발생한 예외를 다시 던지나요(rethrow), 아니면 다른 예외를 던지나요?
• 다른 예외인 경우 원본 예외가 포함되나요?

또한 함수가 인라인(inline)으로 선언되지 않은 경우, 동시성(concurrency)과 관련된 모든 특수 동작을 문서화하십시오. 다음 사항들이 포함되었는지 확인하십시오.

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

문서 내 명시적 링크 사용

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

@see 태그나 내부 링크를 사용하여 문서에서 이러한 관계를 명시하십시오. 이렇게 하면 독자가 정보를 청크(chunk)화하여 라이브러리에 대한 보다 통합된 멘탈 모델(mental map)을 구축할 수 있도록 도와줍니다.

가능한 경우 자체 완결적으로 작성

입력의 유효성을 설명할 때 W3C, IEEE 또는 Unicode Consortium에서 제공하는 관련 표준을 단순히 참조하고 싶은 유혹이 생길 수 있습니다. 이러한 링크를 제공하는 것이 도움이 될 수는 있지만, 공백 문자 집합과 같은 기본적인 정보를 찾기 위해 독자가 외부 명세서를 참조하도록 강요해서는 안 됩니다.

가능한 한 문서는 자체 완결적(self-contained)이어야 합니다. 사용자가 각 API 진입점의 일반적인 사용법을 이해할 수 있을 만큼 충분한 정보를 제공해야 합니다. 일반적인 사용에서 발생하지 않는 에지 케이스에 대해서만 외부 문서를 참조하도록 하십시오.

쉬운 영어 사용

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

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

다음 단계

아직 확인하지 않았다면 다음 페이지들을 살펴보십시오.

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