빛망울 효과 프로젝트

이 페이지에는 Google Season of Docs에서 수락된 기술 작문 프로젝트의 세부정보가 포함되어 있습니다.

프로젝트 요약

오픈소스 조직:
빛망울 효과
테크니컬 라이터:
vis_verborum
프로젝트 이름:
만들기, 읽기, 공유: Bokeh 문서 최적화
프로젝트 기간:
표준 기간 (3개월)

Project description

만들기, 읽기, 공유: Bokeh 문서 최적화

1. 요약

빛망울 효과는 Python으로 브라우저 기반 대화형 시각화를 만들 수 있는 매우 강력한 도구입니다. 상당한 사용자 기반 (월별 콘다 다운로드 502,000건, PyPi 다운로드 855,000건)과 많은 참여자 (GitHub에 참여자 455명)를 갖추고 있습니다. Bokeh의 광범위한 문서가 유기적으로 증가한다는 것은 놀라운 일이 아닙니다. 따라서 일관되지 않고 액세스하기 어렵고 복잡합니다.

Google의 Season of Docs는 Bokeh 문서의 구조와 내용을 집중적으로 검토하고 수정할 수 있는 특별한 기회를 제공합니다. 또한 문서와 관련 도구 및 워크플로가 미래에 대비할 수 있도록 보장합니다.

Python 및 Sphinx (최신 버전: PyZillow 및 PyPresseportal)로 오픈소스 프로젝트를 코딩하고 문서화했습니다. 하지만 저를 Google의 Docs 시즌에 특별하게 참여하게 된 건 제가 언론 업계에 종사한 경험이 있다는 점입니다. 저는 언론사에서 13년 넘게 근무하면서 디지털 변화를 지지하는 편집장으로 수년 동안 일했습니다. 저널리즘 업무 외에도 새로운 디지털 도구와 스타일 가이드를 설계하고 문서화하는 것은 물론 뉴스룸 직원 교육도 담당했습니다.

최근 유럽에서 미국으로 이주한 후 저는 커뮤니케이션과 코딩에 대한 열정을 한데 모아 새로운 방법을 모색하기로 했습니다. 기술 글쓰기는 저의 글쓰기와 기술 분야에서 저의 기술과 경험을 최적으로 조합하는 것이었습니다. 이 제안서에서는 제가 어떻게 하면 빛망울 효과의 문서를 최적화하기 위해 Google의 Season of Docs를 활용할 것입니다. 즉, 문서를 더 간단하게 읽고 문서의 정보를 다른 사람들과 공유함으로써 더 편리하게 문서를 만들고 기여할 수 있습니다.

2. 현재 상황

Bokeh의 공식 문서는 다음과 같은 주요 단위로 구성됩니다.

  • 설명 문서: 설치 가이드, 사용자 가이드, 개발자 가이드, 출시 노트
  • 갤러리 및 데모 (소스 코드가 포함된 양방향 예제)
  • 참조 가이드 (docstrings 기반 문서)
  • 튜토리얼 (mybinder.org에서 호스팅되는 광범위한 Jupyter 노트북 컬렉션)
  • IDE를 위한 docstring 및 모델 도움말
  • 프로젝트 저장소의 예시 및 README

또한 Bokeh 지원 포럼과 Bokeh의 개발자가 사용자의 질문에 적극적으로 답변하는 Stack Overflow와 Bokeh의 Medium 블로그에서도 다양한 정보를 확인할 수 있습니다.

대부분의 문서 웹페이지는 여러 표준 및 맞춤 Sphinx 확장 프로그램을 사용하여 Sphinx로 생성됩니다. 예를 들어 참조 가이드는 'autodoc' 및 맞춤형 'bokeh_autodoc'과 같은 확장자를 사용하여 docstring에서 생성됩니다. 유기적으로 생성된 문서의 특성과 마찬가지로 중복 및 불일치를 포함합니다.

기존 문서를 분석할 때 가장 먼저 발견한 것 중 하나는 문서 작성을 위한 명확한 스타일 가이드라인이 없다는 점이었습니다. Bokeh 개발자 가이드에는 몇 가지 기본 안내가 포함되어 있습니다. 그러나 이 문서에는 스타일, 특히 docstring을 벗어나는 문서에 대한 안내가 많지 않습니다. 따라서 스타일 및 구조적인 문제로 인해 문서 정보에 액세스하기가 더 어려워지며, 특히 처음 사용하는 사용자는 더욱 그렇습니다.

예를 들면 다음과 같습니다.

Bokeh의 문서 방문 페이지는 다소 짧으며 사용 가능한 모든 리소스에 대한 정보가 포함되어 있지 않습니다 (광범위한 docstring 및 모델 도움말 함수 라이브러리, 지원 포럼, 데모 또는 Medium 블로그는 언급되지 않음). 따라서 신규 사용자가 빛망울 효과를 사용하기가 더 어려워집니다.

3. 목표

11주의 문서 개발 단계를 가장 효율적으로 활용하기 위해 다음 세 가지 핵심 요소에 중점을 두겠습니다.

3.1. 문서 작성 개선

Bokeh 문서의 대부분은 새로운 기능 및 버그 수정에 대한 pull 요청의 일부로 문서를 포함하는 기여자가 작성합니다. 문서 개발 단계를 사용하여 기존 문서를 수정하고 리팩터링하겠지만, 문서 생성 및 유지관리 워크플로가 미래에도 활용될 수 있도록 만드는 것을 강조하고 싶습니다. 기여자가 최대한 쉽게 높은 수준의 문서를 일관되게 유지하는 것이 가능해야 합니다.

다음 두 가지 접근 방식을 통해 이를 보장해 보겠습니다.

  • 기존 개발자 가이드에 포함될 실용적이고 간단한 스타일 가이드라인을 만들어 보겠습니다. 이 가이드라인은 스타일, 문법, 구조를 다룹니다. 또한 Slack과 같은 내부 커뮤니케이션 채널을 사용하여 Bokeh 기여자가 스타일 가이드라인을 인지하도록 할 것입니다. 또한 팀을 위한 일대일 교육과 Q&A 세션도 제공할 예정입니다.
  • 핵심 팀과 협력하여 문서 품질 관리를 위한 최적의 도구 모음을 찾아 보겠습니다. 이 도구 모음은 Bokeh의 기존 PR (pull 요청) 및 CI (지속적 통합) 워크플로에 추가될 예정입니다. 팀의 요구사항에 따라 Bokeh의 테스트 모음에 pydocstyle, proselint, sphinxcontrib-spelling 맞춤법 검사와 같은 도구를 추가하거나 사전 커밋 설정 또는 GitHub 작업을 수행해야 할 수 있습니다. 자체 오픈소스 프로젝트 중 하나의 GitHub 작업에 실제 개념 증명을 추가했습니다.

3.2. 문서 읽기 개선

좋은 문서화의 목표는 현재 사용자와 잠재 사용자가 정확한 정보를 쉽게 찾고 이 정보를 최대한 효율적으로 활용할 수 있도록 하는 것입니다.

텍스트의 사용성에 대한 핵심 요소는 텍스트의 스타일과 구조입니다. 명확하고 일관된 스타일로 문서를 작성하면 독자가 주의를 산만하게 하거나 불필요한 언어 없이 정보를 빠르게 찾을 수 있습니다. 직관적이고 직관적인 문서 구조로 관련 정보를 쉽고 빠르게 찾을 수 있습니다.

신규 사용자를 위한 사용성에 초점을 맞춰 이 두 가지 영역을 중점적으로 다뤄보겠습니다. 이를 위해 사용자 가이드를 중심으로 내러티브 문서를 철저히 검토해야 합니다. 또한 다양한 타겟층에 대해 보다 명확하게 설명하고 모든 사용자가 적절한 리소스를 신속하게 찾을 수 있도록 문서 방문 페이지를 개편할 것입니다.

위에서 설명한 문서 작성을 개선하는 것과 마찬가지로, 앞으로의 개선을 위한 토대를 마련하고 Bokeh 문서에 대한 높은 표준을 계속 높이는 데 집중할 것입니다.

3.3. 문서 공유 개선

서드 파티 플랫폼에서 빛망울 효과(Bokeh)에 대한 논의가 점점 더 많아지고 있습니다. 이러한 플랫폼에서는 대부분 Facebook의 오픈 그래프 와 같은 메타데이터를 사용하여 링크의 다양한 미리보기를 포함합니다. OpenGraph는 Facebook, Twitter, LinkedIn, Slack, iMessage 등의 서비스에서 사용됩니다. Bokeh의 Discourse 포럼은 OpenGraph를 사용하여 링크 미리보기를 렌더링하기도 합니다.

이 기술을 활용하기 위해 문제 #9792에 설명된 대로 Bokeh의 Sphinx 생성 웹페이지에 메타데이터를 추가하겠습니다. 가장 효율적인 방법은 전용 Sphinx 확장 프로그램을 사용하는 것입니다. 며칠 전 OpenGraph 데이터용 Sphinx 확장 프로그램의 첫 버전이 GitHub에 게시되었습니다. 이 확장 프로그램을 Bokeh 문서에 사용할 수 있도록 개선하기 위해 문서 개발 단계의 일부를 사용하겠습니다.

또한 내 오픈소스 프로젝트 중 하나인 PyPresseportal에서 성공적으로 사용하고 있는 개념 증명을 만들었습니다. 이 확장 프로그램은 제목, 설명, 이미지, URL과 같은 관련 정보를 자동으로 수집합니다. 그런 다음 이 정보를 Sphinx에서 생성된 HTML 코드에 OpenGraph 태그로 삽입합니다.

이 확장 프로그램을 개발하는 다음 단계는 OpenGraph 메타데이터를 수동으로 정의하는 맞춤형 지시문을 도입하는 것입니다 (docutil의 기존 'meta' 지시문과 유사). 자동 생성된 메타데이터는 수동으로 입력한 데이터가 없는 경우 대체 수단으로만 사용됩니다.

구조화된 데이터 지원은 훨씬 더 복잡하므로 주로 Bokeh 문서에 대한 고품질 OpenGraph 메타데이터를 포함하는 데 중점을 두겠습니다. 오픈 그래프 지원에 필요한 모든 작업은 이와 동시에 구조화된 데이터 지원의 토대가 됩니다.

Sphinx 및 ReadTheDocs 커뮤니티 회원들이 오픈 그래프 및 구조화된 데이터용 확장 프로그램 (예: 문제 #1758 및 #5208) 개발에 관심을 보였으며, 저도 이들과 긴밀히 협력할 것입니다.

4. 결과물

Season of Docs에서 얻게 될 결과물은 다음과 같습니다.

  • Bokeh 참여자를 위한 문서 스타일 가이드라인
  • 자동화된 문서 품질 관리를 포함하도록 PR 및 CI 워크플로 수정
  • 사용자 가이드 수정 및 재구성
  • 수정된 문서 방문 페이지
  • 문서 웹페이지 및 작동하는 Sphinx 확장 프로그램에 포함된 OpenGraph 메타데이터

또한 개인 웹사이트/Medium 또는 Bokeh의 Medium 블로그에 Google의 Docs 시즌을 사용한 여정을 기록하기 위해 '문서 로그'를 보관하겠습니다. 이는 Google 프로젝트 보고서의 기본 자료로도 사용됩니다. 가능하다면 GitHub 문제 및 pull 요청의 형태로 모든 업무를 투명하게 처리하겠습니다.

5. 타임라인

커뮤니티 유대감 단계 전: 저는 이미 Bokeh의 GitHub 저장소에 대한 여러 토론에 적극적으로 참여하고 있으며, Google의 Docs 시즌에 대한 Bokeh의 멘토인 Bryan Van de Ven 및 Pavithra Eswaramoorthy와 연락을 주고받습니다. 나는 빛망울 효과에 관한 대화에도 적극적으로 참여할 것이며, 시각화를 빌드하고 게시함으로써 빛망울 효과에 더 익숙해질 것입니다.

커뮤니티 활동 단계 (8월 17일~9월 13일):

  • 핵심 팀에 대해 알아보고 멘토와의 대가로 프로젝트 계획 조정
  • 멘토와의 정기적인 보고 및 피드백을 위한 일정과 커뮤니케이션 채널 설정
  • Bokeh의 Slack을 적극적으로 활용하여 관심 있는 모든 Bokeh 참여자에게 Google의 Docs 시즌과 문서 개발 단계의 목표에 관해 알립니다.
  • Bokeh 참여자의 의견을 수집하여 문서 개발 단계를 더욱 개선합니다.

문서 개발 단계

1주차, 9월 14일~9월 20일:

  • 내러티브 문서 감사 및 수정 시작
  • 스타일 가이드라인 초안 작성 시작

2주차, 9월 21일~9월 27일:

  • 스타일 가이드라인 작업 계속하기
  • 설명 문서 계속 수정
  • 문서 방문 페이지 정비 시작

3주 차, 9월 28일~10월 4일:

  • 스타일 가이드라인 마무리
  • 문서 방문 페이지 완료

10월 5일~10월 11일 4주차:

  • 설명 문서 편집 완료
  • Bokeh 핵심팀과 PR/CI 워크플로의 문서 품질관리를 위한 도구 통합에 대해 논의

10월 12일~10월 18일 5주 차:

  • Slack에서 Bokeh 참여자와의 Q&A 세션을 설정하여 스타일 가이드라인, 내러티브 문서 개선 사항, PR/CI 워크플로를 논의합니다.
  • 오픈 그래프 메타데이터에 대한 기존 개념 증명을 배포 가능한 Sphinx 확장 프로그램으로 개발하기 시작합니다.
  • 빛망울 효과 사용자와의 Q&A 세션의 의견을 바탕으로 스타일 가이드라인 수정

6주 차, 10월 19일~10월 25일:

  • PR 및 CI 워크플로에서 문서 품질 관리를 위한 도구 테스트 시작
  • 메타데이터용 Sphinx 확장 프로그램 개발 계속

10월 26일~11월 1일 7주차

  • Sphinx 확장 프로그램 테스트
  • Slack의 빛망울 효과 참여자와의 두 번째 Q&A 세션
  • 두 번째 Q&A 세션의 피드백을 기반으로 결과물 수정

8주 차, 11월 2일~11월 8일:

  • Sphinx 확장 프로그램을 배포하고 개선된 내러티브 문서 및 문서 방문 페이지를 게시합니다.

9주 차, 11월 9일~11월 15일:

  • 문서 품질 관리 도구를 PR 및 CI 워크플로에 배포
  • 스타일 가이드라인과 PR 및 CI 워크플로 추가를 포함하도록 개발자 가이드 업데이트 및 게시

11월 16일~11월 22일 10주 차:

  • 나머지 작업 완료하기

11월 23일~11월 29일 주간:

  • 프로젝트 보고서 작성 시작
  • 프로젝트 평가 작성 시작

프로젝트 완료 단계

11월 30일~12월 5일 12주 차:

  • 프로젝트 보고서 마무리 및 제출

12월 3일~12월 10일 13주 차:

  • 프로젝트 평가 완료 및 제출

Google 문서 시즌 종료 후:

  • 저는 Bokeh 개발에 계속 참여하고 Bokeh 관련 문서 작업을 계속하고 싶습니다.
  • 오픈 그래프/구조화된 데이터 메타데이터용 Sphinx 확장 프로그램 개발을 계속할 계획입니다.
  • 저는 저널리즘 분야에서 쌓은 경험과 기존 네트워크를 활용하여 Bokeh를 데이터 저널리즘의 도구로 홍보하고 싶습니다. 예를 들어 언론인 독자를 염두에 두고 Bokeh에 대해 글을 쓰거나 언론 환경에서의 Bokeh 사용에 관한 컨퍼런스 대담을 진행합니다.

6. 내 정보

저는 언론인으로, TV, 온라인, 라디오 뉴스 경험이 있습니다. TV 및 디지털 뉴스 편집장 겸 리포터로 일하면서 수년 간 글쓰기와 편집 분야에서 경험을 쌓았습니다. 동시에 디지털 혁신과 자동화를 촉진하는 여러 프로젝트에 참여했습니다. 저는 디지털 도구 및 워크플로에 관한 수많은 매뉴얼, 그리고 디지털 뉴스 브랜드를 위한 스타일 가이드와 커뮤니케이션 전략을 저술했습니다. 또한 팀원들에게 이러한 도구를 사용하는 방법을 교육했습니다.

저는 항상 커뮤니케이션과 기술의 교차점에 끌렸습니다. Python으로 코딩하는 방법을 배웠을 때 완전히 새로운 세계가 열렸습니다. 예를 들어 데이터 저널리즘을 위해 데이터 분석과 시각화를 할 수 있었습니다. 코딩을 학습한 덕분에 소프트웨어 엔지니어와 적극적으로 협업하여 언론사 워크플로를 위한 디지털 도구를 개발할 수 있었습니다.

이전 직장에서 작성한 매뉴얼과 문서는 비공개 상태입니다. 따라서 이제는 오픈소스 프로젝트에 더 적극적으로 참여하는 데 집중하고 있습니다 (아래 예시 참고). Google의 개발자 문서 스타일 가이드 및 Microsoft 스타일 가이드와 같은 스타일 가이드를 바탕으로 기술 문서 작업을 했습니다. GitHub, Slack, Linux를 자주 사용합니다. 저는 Sphinx, Mypy, Sphinx autodoc 같은 도구를 사용해 서술 문서, docstring, 유형 힌트를 작성하고 있습니다.

현재 프리랜서로 일하고 있습니다. 제 일정은 문서 개발 단계에서 주당 약 25시간 동안 Bokeh 문서를 작성하는 데 필요한 유연성을 제공합니다. 태평양 표준시에서 근무하고 있지만 팀의 일정과 요구사항을 기꺼이 수용합니다.

7. 최신 오픈소스 문서 예시

  • PyZillow: PyZillow는 부동산 웹사이트 Zillow.com의 API를 위한 Python 래퍼입니다. 몇 가지 코드를 제공하고 코드 유지관리 담당자 역할을 하는 것 외에 전체 문서도 작성했습니다. 서술형 문서와 모듈 참조용으로 Sphinx를 사용했습니다. 코드에 추가한 docstring을 기반으로 Sphinx 확장 프로그램 autodoc로 모듈 참조를 만들었습니다.

  • PyPresseportal: PyPresseportal은 웹사이트 presseportal.de의 API를 위한 Python 래퍼입니다. presseportal.de 웹사이트는 독일에서 보도자료 및 투자자 관계 발표를 제공하는 최대 배포자 중 하나입니다. 예를 들어 거의 모든 경찰서와 소방서에서 보도자료를 배포하는 데 이 서비스를 사용합니다. 언론인으로 수년간 API를 사용해 온 저는 웹사이트의 광범위한 데이터 리소스에 Python 객체로 액세스할 수 있는 Python 인터페이스를 개발하기로 했습니다. 코드와 전체 Sphinx 기반 문서를 작성했습니다.