빛망울 효과 프로젝트

이 페이지에는 Google Season of Docs에서 승인된 테크니컬 라이팅 프로젝트의 세부정보가 포함되어 있습니다.

프로젝트 요약

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

Project description

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

1. 개요

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

Google의 Docs 시즌은 Bokeh 문서의 구조와 내용을 집중 검토 및 수정하고 문서 및 관련 도구 및 워크플로가 미래에도 활용될 수 있도록 하는 특별한 기회를 제공합니다.

저는 Python 및 Sphinx (최근 출시: PyZillow 및 PyPresseportal)로 오픈소스 프로젝트를 코딩하고 문서화했습니다. 하지만 저를 Google 문서 시즌에 특별하게 참여한 이유는 제가 저널리즘에 종사한 경험이 있기 때문입니다. 언론사에서 13년 넘게 근무하면서 디지털 변화를 지지하는 상무 편집자이자 옹호자로 일했습니다. 언론 활동을 하는 것 외에도 새로운 디지털 도구와 스타일 가이드를 설계하고 문서화하고 언론사 직원을 교육하는 등 여러 업무를 담당했습니다.

최근 유럽에서 미국으로 이주한 후 저는 커뮤니케이션과 코딩에 대한 저의 열정을 불러일으키는 새로운 방법을 모색하기로 했습니다. 저는 기술 문서 작성이 글쓰기와 기술 분야에서 저의 기술과 경험을 최적으로 조합하는 것이라고 생각합니다. 이 제안서에서는 빛망울 효과의 문서를 최적화하기 위해 Google의 Docs 시즌을 사용하는 방법을 설명하겠습니다. 더 간단하게 문서를 작성하고 기여할 수 있도록 돕고, 더 간단하게 문서를 읽고 문서의 정보를 다른 사람들과 더 쉽게 공유합니다.

2. 현재 상황

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

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

또한 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 세션도 제공할 예정입니다.
  • 핵심 팀과 협력하여 최적의 문서 품질 관리를 위한 도구 모음을 찾을 예정입니다. 이 도구 모음은 PR (pull 요청) 및 CI (지속적 통합)용 Bokeh 기존 워크플로에 추가될 예정입니다. 팀의 요구사항에 따라 이는 pydocstyle, priselint, sphinxcontrib-spelling 맞춤법 검사와 같은 도구를 Bokeh의 테스트 모음, 사전 커밋 설정 또는 GitHub 작업에 추가해야 할 수 있습니다. 자체 오픈소스 프로젝트 중 하나의 GitHub 작업에 실제 개념 증명을 추가했습니다.

3.2. 문서 읽기 개선

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

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

저는 신규 사용자를 위한 사용성에 초점을 맞춰 이 두 가지 영역에 초점을 맞출 것입니다. 여기에는 사용자 가이드를 중심으로 한 설명 문서를 철저하게 검토하는 작업이 포함됩니다. 또한 문서 방문 페이지를 정비하여 다양한 타겟층을 더 명확하게 다루고 모든 사용자가 적절한 리소스를 신속하게 찾을 수 있도록 할 것입니다.

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

3.3. 문서 공유 개선

서드 파티 플랫폼에서 빛망울 효과에 대한 논의가 점점 더 많아지고 있습니다. 이러한 플랫폼 중 다수는 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 커뮤니티의 회원들이 OpenGraph 및 구조화된 데이터용 확장 프로그램 (예: #1758 및 #5208)의 개발에 관심을 보였으며, 앞으로도 이들과 긴밀히 협력할 것입니다.

4. 결과물

요약하자면, Docs 시즌에서 나올 것으로 예상되는 결과물은 다음과 같습니다.

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

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

5. 타임라인

커뮤니티 유대감 단계 전: 저는 이미 Bokeh의 GitHub 저장소에 관한 여러 토론에 적극적으로 참여하고 있으며, Google의 Docs 시즌에 대한 Bokeh의 멘토인 브라이언 반 데 벤, 파비트라 에스와라무시와 연락을 주고받습니다. 저는 빛망울 효과에 관한 대화에 적극적으로 참여하며 시각화를 만들고 게시함으로써 빛망울 효과에 대해서도 더 자세히 알아보고자 합니다.

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

  • 핵심 팀에 대해 알아보고 멘토의 도움을 받아 프로젝트 계획을 다듬으세요.
  • 멘토와의 정기적인 보고 및 의견 제공을 위한 일정 및 커뮤니케이션 채널 설정
  • 관심 있는 모든 빛망울 효과 기여자에게 Google의 Docs 시즌과 문서 개발 단계의 목표에 대해 알리려면 Bokeh의 Slack을 적극적으로 활용하세요.
  • 빛망울 효과 참여자의 의견을 수집하여 문서 개발 단계를 더욱 세부적으로 계획합니다.

문서 개발 단계

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

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

2주차 2021년 9월~27일:

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

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

  • 스타일 가이드라인 마무리하기
  • 문서 작성 방문 페이지

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

  • 내러티브 문서 편집 완료
  • PR/CI 워크플로에서 문서 품질 관리를 위한 도구를 통합하는 것에 대해 Bokeh 핵심팀과 논의

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

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

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

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

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

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

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

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

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

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

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

  • 나머지 작업 완료하기

11월 23일~11일 차:

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

프로젝트 완료 단계

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

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

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

  • 프로젝트 평가 마무리 및 제출

Google 문서 시즌이 끝난 후:

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

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 기반 문서를 작성했습니다.