pub.dev 패키지 페이지 잘 작성하기

pub.dev 패키지 페이지 잘 작성하기

pub.dev에서 좋은 패키지 페이지를 만들기 위한 지침을 정리했어요. 특히 패키지 README를 더 잘 쓰는 팁에 집중해요. README는 패키지 페이지에서 README(이 문서)로 표시되는 내용이에요.

출처: Writing package pages

본문

pub.dev에서 좋은 패키지 페이지를 만들려면 이 페이지의 지침이 도움이 돼요. 특히 더 나은 패키지 README를 쓰기 위한 팁을 다루는데, README는 다음 스크린샷에서 README(이 문서)로 표시된 내용을 제공해요. 패키지 페이지의 다른 부분에 대한 자세한 내용은 다음 링크를 참고하세요.

좋은 README를 쓰는 게 중요한 이유

pub.dev에서 패키지를 발견한 사람들은 그 패키지를 시도할지 결정할 때 README를 빠르게 훑어볼 가능성이 높아요. 좋은 README는 독자의 관심을 끌고 패키지가 시도해 볼 가치가 있다는 걸 보여 줘요.

참고: 패키지 README는 여러 방식으로 사용돼요. 그 내용이 pub.dev의 패키지 페이지뿐 아니라 dart doc이 만든 API 참조 문서에도 나타나기 때문이에요.

이 페이지는 in_app_purchase 패키지 README를 예시로 들지만, 여러분의 README가 그만큼 크거나 상세할 필요는 없어요. 패키지가 단순하고 연관된 UI가 없다면 README는 yaml 패키지의 것처럼 보일 수도 있어요.

좋은 README를 위한 7가지 팁

pub.dev에서 잘 동작하는 README를 만들기 위한 몇 가지 제안이에요.

  • 위에 짧은 설명을 넣으세요.
  • 시각적 콘텐츠를 포함하세요.
  • 목록을 사용해 중요한 정보를 제시하세요.
  • 사용 예시를 포함하세요.
  • Dart 코드 포맷을 사용하세요.
  • 관련 용어를 언급하세요.
  • 사용자에게 다음 단계를 알려 주세요.

1. 위에 짧은 설명을 넣으세요

사용자 조사에 따르면 패키지 사용자는 패키지 설명을 읽고 나머지 README를 읽을지 결정하는 데 단 몇 초밖에 쓰지 않아요. 따라서 패키지가 무엇을 하거나 달성하는지 한눈에 간결하게 설명해야 해요. 짧고 좋은 설명을 만드는 데 시간을 들여서 사용자가 결정을 내리도록 도와주세요.

팁: 위에 패키지 이름을 다시 쓰지 마세요. pub.dev UI에 이미 보이고 있거든요.

좋은 설명의 예는 다음과 같아요.

  • A Flutter plugin for showing rainbows.
  • Use machine learning to categorize bird sounds.

프로젝트 상태나 제약 같은 중요한 정보도 위쪽에 가까이 있어야 해요. 예를 들면:

  • Does not work on iOS versions below 10.3.

배지는 흔히 README의 위쪽, 짧은 설명 위나 아래에 놓여요.

2. 시각적 콘텐츠를 포함하세요

패키지 페이지가 시각적 콘텐츠 없이 텍스트 벽이라면 사용자가 부담을 느끼고 읽기를 멈출 수 있어요. 이미지는 패키지가 UI를 지원하는 경우 특히 중요하지만, 중요한 개념을 설명하는 데도 유용해요. 어느 쪽이든 시각적 콘텐츠는 사용자가 패키지를 자신 있게 쓸 수 있게 도와줘요.

정적 이미지, 애니메이션 GIF, 비디오(MOV 또는 MP4 파일 같은 것) 같은 시각적 콘텐츠를 README 초반부, 사용자가 보기 쉬운 곳에 배치하세요.

팁: UI 관련 콘텐츠에는 애니메이션 GIF와 비디오를 선호하세요. 대부분의 UI는 정적이지 않고, 애니메이션이 UI 동작에 대한 더 많은 정보를 전달해 주거든요.

팁: 시각적 콘텐츠를 추가할 때는 파일에 절대 URL을 사용해서 README가 게시되는 곳에 관계없이 이미지가 확실히 나타나게 하세요. 이미지를 호스팅할 곳 중 하나는 저장소 자체예요. in_app_purchase가 그렇게 해요.

3. 목록을 사용해 중요한 정보를 제시하세요

목록은 README에서 중요한 정보에 주의를 끌 수 있어요. 목록을 쓸 만한 것들은 다음과 같아요.

  • 패키지의 핵심 기능
  • 파라미터, 속성, 프로퍼티
  • 특별한 요구 사항
  • 패키지 범위 밖의 기능
  • 페이지나 페이지 내 섹션의 내용 요약(이 목록처럼)

보통 목록은 위와 같은 불릿 목록이에요. 또 다른 옵션은 표를 사용하는 것이고, 다음 섹션의 플랫폼 지원 표처럼요.

패키지의 핵심 기능 (Key features of the package)

먼저 패키지가 무엇을 할 수 있는지 명확히 나열하세요. 어떤 사용자는 매우 특정한 기능을 찾고 있을 수 있어요. 그런 사용자가 패키지가 자신의 요구를 지원하는지 알 수 있게 도와주세요.

파라미터, 속성, 프로퍼티 (Parameters, attributes, or properties)

빠르게 참조할 수 있도록 파라미터, 속성, 프로퍼티를 나열하는 것을 고려하세요. (다시 말하지만, 패키지 README의 내용은 패키지 페이지뿐 아니라 API 참조 문서에도 나타난다는 점을 기억하세요.) 예를 들어 url_launcher 패키지는 지원되는 URL 스킴의 표를 가져요. 또한 API 참조 문서의 특정 함수나 클래스로 연결하는 것도 유용할 수 있어요. async 패키지에서 예제를 볼 수 있어요.

특별한 요구 사항 (Unusual requirements)

패키지가 모든 패키지가 요구하는 것 이상으로 특정 설정을 요구한다면 README에 설정 지침을 나열하세요. 예를 들어 google_maps_flutter 패키지의 다음 스크린샷은 Google Maps Platform 시작 방법에 대한 지침을 보여 줘요.

패키지 범위 밖의 기능 (Functionality that's out of scope of your package)

사용자가 패키지가 도움이 될지 알 수 있도록, 사용자가 기대할 수 있지만 패키지가 지원하지 않는 기능을 나열하세요. 언제 범위 밖 기능을 나열하고 싶을지의 예는 다음과 같아요.

  • 버튼 패키지가 아이콘 버튼이 아니라 텍스트 버튼에만 집중한다면 README에 그걸 분명히 하세요.
  • 패키지가 특정 버전의 Android만 지원한다면 README에 그렇게 말하세요.

목차 (Contents)

페이지나 섹션에 목차가 있으면 사용자가 더 쉽게 탐색할 수 있어요. README의 섹션이 매우 길다면 섹션 시작 부분에 하위 섹션을 명확히 나열하는 것을 고려하세요. 예를 들어 in_app_purchase README의 "Usage" 섹션은 많은 예시가 있는데, 목차를 사용하면 사용자가 어떤 예시가 있는지 이해하고 관심 있는 코드로 갈 수 있어요.

4. 사용 예시를 포함하세요

패키지가 유망해 보이면 사용자가 패키지를 테스트하고 싶어할 수 있어요. 사용자가 쉽게 이해할 수 있는 코드 샘플을 최소한 하나 포함한 "Get started" 또는 "Usage" 섹션을 넣으세요. 이상적으로는 프로젝트에 복사해서 붙여 넣을 수 있는 코드죠. 더 상세한 예시를 더 많이 제공해서 사용자가 패키지를 이해하도록 도와주면 더 좋아요.

모든 사용자가 영어를 한다고 생각하지 마세요. 하지만 모두 Dart를 하잖아요! 좋은 코드 샘플은 큰 도움이 돼요. 패키지의 example 디렉토리 아래에 더 완전한 예시를 추가하는 것도 고려하세요. pub.dev가 Examples 탭을 채우는 데 사용할 수 있거든요. 자세한 내용은 패키지 레이아웃 규칙의 Examples를 참고하세요.

5. Dart 코드 포맷을 사용하세요

코드 예시를 추가할 때는 백틱 세 개(```````) 대신 백틱 세 개에 dart를 붙인 것(````dart)을 사용하세요. 다음 예시가 보여 주듯이 dart`를 붙이면 pub.dev에 Dart 구문 강조를 사용하라고 알려 줘요.

final like = 'this';

final like = 'this';

6. 관련 용어를 언급하세요

최근 UX 연구에 따르면 많은 사용자가 페이지 내 검색 기능(Cmd/Ctrl+F)을 사용해서 찾고 있는 기능을 검색해요. 따라서 README에 중요한 용어를 꼭 언급해서 사용자가 그 용어를 찾을 수 있게 하세요.

예를 들어 사용자는 in_app_purchase 패키지가 인앱 구독을 지원하는지 알고 싶을 수 있어요. subscription이라는 키워드를 검색하는 사용자는 그 페이지가 그 용어를 쓰지 않는다면 페이지를 떠날 수도 있어요(subscription은 한국어로 '구독'). 사람들이 검색할 만한 모든 용어를 언급한 후에는 사용하는 용어를 일관되게 유지하세요. 필요하다면 용어를 명확히 정의하세요. 예를 들어 in_app_purchase 패키지는 시작 부분에서 underlying store를 정의하고, 이후 페이지 전체에서 그 용어를 일관되게 사용해요.

7. 사용자에게 다음 행선지를 알려 주세요

사용자가 패키지에 대해 더 알아볼 수 있게 도와주세요. 잠재 사용자에게 알려 줄 만한 것은 다음과 같아요.

  • 패키지에 대해 더 배울 곳. Medium의 문서나 YouTube의 비디오에 연결할 수 있어요.
  • 패키지 사용에 대한 도움을 받을 곳. 이슈 트래커, 채팅방, 이메일 주소 같은 것들이 가능해요.
  • 패키지로 무엇을 계획하고 있는지. README 안이나 외부 페이지의 로드맵은 사용자가 필요한 기능이 곧 나올지 알게 해 줘요.
  • 패키지에 코드를 기여하는 방법.

좋은 README 작성에 대해 더 배우기

이 문서에서 좋은 README를 위한 7가지 팁을 제안했어요. 개발자 문서 작성에 대한 일반적인 권장 사항은 Google Developer Documentation Style Guide에서 더 배울 수 있어요. 추가 팁은 다음과 같아요.

  • 이미지에 대체 텍스트(alt text)를 제공하세요.
  • 간결하게 쓰세요. "please"는 쓰지 마세요.
  • 줄 길이를 80자 이하로 유지하세요.
  • 코드를 올바르게 포맷하세요(dart format이 하듯이).

좋은 README 작성에 대해 더 자세히 보려면 다음 자료를 참고하세요.

이 페이지와 다른 페이지의 제안이 모든 패키지에 맞지는 않을 수 있어요. 창의적으로 하세요! 사용자의 입장이 되어 독자가 무엇을 읽고 알기를 원할지 상상해 보세요. 독자가 필요한 정보를 제공할 수 있는 사람은 여러분뿐이에요.

더 알아보기