빛망울 효과 프로젝트

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

프로젝트 요약

오픈소스 조직:
빛망울 효과
기술 문서 작성자:
vis_verborum
프로젝트 이름:
만들기, 읽기, 공유: Bokeh 문서 최적화
프로젝트 길이:
표준 기간 (3개월)

Project description

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

1. 개요

Bokeh는 Python으로 브라우저 기반의 대화형 시각화를 만들 수 있는 매우 강력한 도구입니다. 상당한 사용자층 (월간 conda 다운로드 502,000회, PyPi 다운로드 855,000회)과 많은 참여자 (GitHub의 참여자 455명)가 있습니다. Bokeh의 광범위한 문서는 유기적으로 성장한 것은 당연한 일입니다. 따라서 일관성이 없고 접근하기 어렵고 복잡할 수 있습니다.

Google의 문서 시즌은 Bokeh 문서의 구조와 콘텐츠를 집중적으로 검토하고 수정할 수 있는 기회를 제공하며, 문서와 관련 도구 및 워크플로가 미래에 대비할 수 있도록 합니다.

Python 및 Sphinx로 오픈소스 프로젝트를 코딩하고 문서화했습니다 (최근: PyZillow 및 PyPresseportal). 하지만 제가 Google의 Season of Docs에 참여하는 데 있어 특별한 점은 저의 저널리즘 배경입니다. 저는 13년 넘게 뉴스룸에서 근무했으며, 그중 수년간 편집장으로서 디지털 변화를 지지해 왔습니다. 언론인으로서의 업무 외에도 새로운 디지털 도구와 스타일 가이드를 설계하고 문서화하는 것과 뉴스룸 직원을 교육하는 데 점점 더 많은 책임이 주어졌습니다.

최근 유럽에서 미국으로 이사한 후 커뮤니케이션과 코딩에 대한 열정을 결합할 수 있는 새로운 방법을 모색하기로 했습니다. 기술 문서 작성은 작문과 기술에 관한 기술과 경험을 최적화하는 데 가장 적합하다고 생각합니다. 이 제안서에서는 Google의 문서 시즌을 사용하여 Bokeh 문서를 최적화하는 방법을 설명합니다. 문서를 더 편리하게 작성하고 문서에 더 편리하게 참여하고, 문서를 더 간편하게 읽고, 문서의 정보를 다른 사용자와 더 쉽게 공유할 수 있도록 할 것입니다.

2. 현재 상황

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

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

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

대부분의 문서 웹페이지는 여러 표준 및 맞춤 Sphinx 확장 프로그램을 사용하여 Sphinx로 작성됩니다. 예를 들어 참조 가이드는 ‘autodoc’ 및 맞춤형 ‘bokeh_autodoc’와 같은 확장 프로그램을 사용하여 docstring에서 생성됩니다. 유기적으로 성장한 문서의 특성과 마찬가지로 이 문서에는 중복과 비일관성이 포함되어 있습니다.

기존 문서를 분석할 때 가장 먼저 눈에 띈 것은 문서 작성에 관한 명확한 스타일 가이드라인이 없다는 점입니다. Bokeh 개발자 가이드에는 몇 가지 기본 안내가 포함되어 있습니다. 하지만 이 문서에는 스타일에 관한 안내가 많이 포함되어 있지는 않습니다. 특히 문서에서 docstring을 넘어서는 부분에 관한 안내는 없습니다. 그 결과 문체 및 구조적 문제로 인해 특히 신규 사용자는 문서의 정보에 액세스하기가 더 어려워집니다.

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

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

3. 목표

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

3.1. 문서 작성 개선

Bokeh 문서의 대부분은 새로운 기능 및 버그 수정을 위한 pull 요청의 일부로 문서를 포함하는 참여자가 작성한 것입니다. 문서 개발 단계의 일부를 사용하여 기존 문서를 수정하고 리팩터링할 예정이지만, 문서를 만들고 유지 관리하기 위한 워크플로를 미래에 대비하도록 만드는 데 중점을 둘 것입니다. 참여자가 일관되게 높은 수준의 문서를 유지하는 것이 최대한 쉬워야 합니다.

다음 두 가지 방법으로 이를 보장하겠습니다.

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

3.2. 문서 읽기 개선

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

텍스트의 사용성에 중요한 요소는 스타일과 구조입니다. 명확하고 일관된 스타일로 문서를 작성하면 독자가 방해 요소와 불필요한 언어 없이 정보를 빠르게 파악할 수 있습니다. 문서의 직관적이고 투명한 구조를 통해 관련 정보를 쉽게 찾을 수 있습니다.

신규 사용자의 사용성을 강조하면서 두 영역 모두에 중점을 둘 예정입니다. 여기에는 사용자 가이드를 중심으로 서술 문서를 철저히 검토하는 것이 포함됩니다. 또한 다양한 타겟층을 더욱 명확하게 다루고 모든 사용자가 적절한 리소스를 빠르게 찾을 수 있도록 문서 방문 페이지를 정비할 예정입니다.

위에 설명된 문서 작성 개선과 마찬가지로 향후 개선을 위한 기반을 마련하고 Bokeh 문서의 높은 표준을 지속적으로 유지하는 데 집중할 예정입니다.

3.3. 문서 공유 개선

서드 파티 플랫폼에서 Bokeh에 관한 논의가 점점 늘어나고 있습니다. 이러한 플랫폼 중 다수는 Facebook의 오픈 그래프와 같은 메타데이터를 사용하여 링크의 풍부한 미리보기를 포함합니다. OpenGraph는 Facebook, 트위터, LinkedIn, Slack, iMessage와 같은 서비스에서 사용됩니다. Bokeh의 Discourse 포럼에서도 OpenGraph를 사용하여 링크 미리보기를 렌더링합니다.

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

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

이 확장 프로그램을 개발하는 다음 단계는 docutil의 기존 'meta' 디렉티브와 마찬가지로 OpenGraph 메타데이터를 수동으로 정의하는 맞춤 디렉티브를 도입하는 것입니다. 자동 생성된 메타데이터는 수동으로 입력된 데이터를 사용할 수 없는 경우에만 대체 옵션으로 사용됩니다.

구조화된 데이터 지원은 훨씬 더 복잡하므로 Bokeh 문서에 고품질 오픈 그래프 메타데이터를 포함하는 데 중점을 두겠습니다. OpenGraph를 지원하는 모든 작업은 동시에 구조화된 데이터 지원의 기반을 마련합니다.

Sphinx 및 ReadTheDocs 커뮤니티 회원들이 OpenGraph 및 구조화된 데이터 확장 프로그램 개발에 관심을 보였습니다 (예: #1758 및 #5208 문제). 이들과 긴밀히 협력할 예정입니다.

4. 결과물

요약하면 Docs 시즌에서 얻을 수 있는 결과물은 다음과 같습니다.

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

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

5. 타임라인

커뮤니티 결속 단계 전: 이미 Bokeh의 GitHub 저장소에 관한 여러 토론에 적극적으로 참여하고 있으며, Google의 Season of Docs에 참여하는 Bokeh의 멘토인 브라이언 반 데 벤과 파비트라 에스와라무르티와 연락을 주고받았습니다. Bokeh에 관한 대화에 계속 참여하고 시각화를 빌드하고 게시하여 Bokeh에 대해 더 자세히 알아볼 예정입니다.

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

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

문서 개발 단계

1주차(9월 14일~9월 20일):

  • 서술형 문서 감사 및 수정 시작
  • 스타일 가이드라인 초안 작성 시작

2주차(9월 21일~9월 27일):

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

3주차(9월 28일~10월 4일):

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

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

  • 서술 문서 수정 완료
  • PR/CI 워크플로의 문서 품질 관리를 위한 도구 통합에 대해 Bokeh 핵심팀과 논의합니다.

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

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

6주 차(10월 19일~10월 25일):

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

7주차(10월 26일~11월 1일):

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

8주차(11월 2일~11월 8일):

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

9주차(11월 9일~11월 15일):

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

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

  • 남은 작업 마무리

11주 차, 11월 23일~11월 29일:

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

프로젝트 완료 단계

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

  • 프로젝트 보고서 최종 수정 및 제출

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

  • 프로젝트 평가를 완료하고 제출합니다.

Google의 Docs 시즌이 종료된 후:

  • Bokeh 개발에 계속 참여하고 Bokeh 문서 작업을 계속할 수 있기를 바랍니다.
  • OpenGraph/정형 데이터 메타데이터용 Sphinx 확장 프로그램을 계속 개발할 계획입니다.
  • 저널리즘과 기존 네트워크에서 쌓은 경험을 바탕으로 Bokeh를 데이터 저널리즘의 도구로 홍보하고 싶습니다. 예를 들어 언론을 대상으로 Bokeh에 관해 글을 쓰거나 언론 환경에서 Bokeh를 사용하는 방법에 관한 컨퍼런스 강연을 제공하는 경우입니다.

6. 내 정보

저는 원래 언론인으로 TV, 온라인, 라디오 뉴스를 다루었습니다. TV 및 디지털 뉴스 분야의 편집장 겸 리포터로 일하면서 수년간 집필과 편집 분야에서 경력을 쌓았습니다. 동시에 디지털 혁신과 자동화를 장려하는 여러 프로젝트에도 참여했습니다. 디지털 도구 및 워크플로를 다루는 수많은 매뉴얼과 디지털 뉴스 브랜드의 스타일 가이드 및 커뮤니케이션 전략을 작성했습니다. 팀원들에게 이러한 도구를 사용하는 방법도 교육했습니다.

저는 항상 커뮤니케이션과 기술의 교차점에 관심이 많았습니다. Python으로 코딩하는 법을 배우면서 완전히 새로운 세계가 열렸습니다. 예를 들어 데이터 저널리즘을 위한 데이터 분석 및 시각화를 할 수 있게 되었습니다. 코딩을 배우면서 소프트웨어 엔지니어와 적극적으로 협력하여 뉴스룸 워크플로를 위한 디지털 도구를 개발할 수 있었습니다.

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

현재 프리랜서로 일하고 있습니다. 문서 개발 단계에서 Bokeh 문서 작업에 주당 약 25시간을 할애할 수 있는 유연한 일정을 가지고 있습니다. 저는 태평양 시간대에서 근무하지만 팀의 일정과 요구사항을 수용하게 되어 기쁘게 생각합니다.

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

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

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