이 페이지에는 Google Season of Docs에 선정된 기술 문서 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 조직:
- 매트플롯립
- 기술 문서 작성자:
- jeromev
- 프로젝트 이름:
- Matplotlib 진입 경로 개발
- 프로젝트 기간:
- 표준 기간 (3개월)
Project description
소개
올해 Google Season of Docs에 제안된 Matplotlib의 프로젝트는 신규 사용자에게 Matplotlib을 소개하는 데 도움이 되는 콘텐츠를 만드는 것입니다. Matplotlib 항목 경로 개발의 경우 현재 문서의 접근 방식을 대체할 방법을 제안합니다. 저는 업계에 새로 합류한 기술 작가이지만 교육 및 교육 관련 분야에서 경력을 쌓았습니다. 기술 문서 작성과 교육은 서로 공감하고 사용자가 주어진 리소스로 작업을 완료할 수 있도록 돕는 콘텐츠를 제작하는 데 집중하는 밀접한 관련이 있습니다.
이 맥락에서 Matplotlib 문서는 신규 사용자와 공감하는 방식을 개선하면 도움이 됩니다. 현재 대부분의 자료는 무작위 데이터와 라벨이 지정되지 않은 시각 자료로 구성되어 있습니다. 이는 Matplotlib의 시각 자료와 기능을 빠르게 표시하는 데 유용합니다. 하지만 Matplotlib을 처음 사용하는 사용자의 경우 데이터를 시각적으로 변환하는 과정을 살펴보는 것이 쉽지 않습니다.
노출적 접근 방식의 맥락이 이러한 장애물에 대한 해결책입니다. 실제 예를 통해 절차를 작성하면 사용자가 작업하는 환경을 이해하고 있음을 보여줍니다. 이는 작업 완수의 목표 또는 기대에 도달하는 측면에서 문서와 사용자의 관계를 개선합니다.
사용자에게 일관된 파생된 목적이 있습니다. 예를 들어 신발 회사의 데이터 과학자는 시간 경과에 따른 쇼핑 동향을 보여주기 위해 팀에 고객 데이터를 제시해야 합니다. 이 경우 사용자는 Matplotlib을 탐색하고 라이브러리 내의 도구를 활용하여 당면한 작업을 완료하는 방법을 배워야 합니다.
문서를 뒷받침하는 추가 컨텍스트를 제공하면 신규 사용자가 주제를 더 잘 이해할 수 있습니다. 사용자의 파생된 목적은 문서와 유사합니다. 수석 개발자인 톰 카스웰이 2017년 인터뷰에서 '실제로 글을 쓰고 사용자에게 공감할 수 있는 사람을 확보하여 200페이지 분량의 '매트플롯립 소개' 책을 써서 이 글의 주요 항목이 되도록 만드는 것'이라는 비전을 향해 나아가고자 합니다.
설명적 글쓰기의 대체 접근 방식
현재 문서는 Matplotlib의 기능, 즉 사용자가 라이브러리로 할 수 있는 작업을 보여줍니다. 예를 들어 튜토리얼은 기본 메서드에 대한 설명이 포함되지 않은 패턴을 따르는 경우가 많습니다.
{what the method does} -> {parameters} -> {returns} -> {related links} -> {examples}
프로그래밍 문서 및 지원의 경우 사용자가 코드를 직접 실행하여 어떤 일이 일어나는지 파악하는 것이 좋습니다. 프로그래밍 사고방식은 사용자가 주제에 대한 이해도를 높이지만 변환의 학습 곡선에는 지원 콘텐츠가 거의 없습니다. 문서화가 제한되어 있기 때문에 이는 압도적인 문제가 될 수 있습니다.
다이어그램, 이미지 또는 기타 시각 자료를 추가하면 새로운 학습 기회를 만들 수 있습니다. 아래 구조는 새 콘텐츠의 템플릿으로도 적합합니다. 또한 텍스트가 아닌 이미지나 그래픽을 추가하는 이유는 콜아웃 및 코치마크와 같은 기능을 활용하기 위해서일 수 있습니다. 코드가 실행되는 출력으로 변환되는 방식이나 위치를 나타내지 않으면 이미지를 탐색하기 더 어려울 때가 있습니다. 주제에 대한 이해를 높이는 강력한 시각적 요소가 누락되었다고 생각합니다.
{method explanation} -> {expository use case/scenario} -> {sample code} -> {parameters} -> {returns} -> {additional examples} -> {informational topic/subject affinity links}
문서에 설명적 글쓰기를 사용하는 이 대체 접근 방식에는 큰 잠재력이 있습니다. 사용자는 다양한 변환 개념을 확인하여 데이터에 대한 시각화를 개발하는 기본 전략을 더 잘 파악할 수 있습니다. 이 지식을 바탕으로 사용자는 실제 사용 사례를 기반으로 한 예시를 통해 기능을 혁신하고 활용할 수 있습니다.
Matplotlib의 인기가 높아짐에 따라 사용 편의성과 접근성의 일관성이 라이브러리의 명성을 입증해 줍니다. 이러한 특성은 코드 내뿐만 아니라 문서 내에도 표시될 수 있는 패턴과 일반적인 전략을 보여주는 데 적합합니다. Matplotlib이 사용 빈도와 확장되는 리소스에서 알 수 있듯이 사용자가 프로그래밍하기에 간단하고 표준적인 경우 기술 문서에도 적용될 수 있습니다.
사용자는 문제가 발생하면 검색을 사용하여 문제를 해결하는 경우가 많습니다. 검색을 기본 탐색 방법으로 사용하기보다는 사용자가 문서 내에서 자체 교육과정을 빌드하도록 하는 것이 더 효과적일 수 있습니다. 즉, 사용자가 문제의 해결 방법을 검색한 후 다른 문제가 발생하거나 추가 정보가 필요하면 전체적으로 삽입된 상세한 링크를 활용하게 됩니다.
이를 위해서는 조직 시스템에 하향식 아키텍처가 필요합니다. Matplotlib 내의 모든 주제에 대해 주제 관심분야 및 정보 제공 주제로 연결되는 풍부한 네트워크 링크는 강력한 네트워크를 구축하는 데 도움이 될 것입니다. 이 네트워크 전반에서 사용자는 자신의 주제로 이동하고 해당 주제와 관련된 더 많은 정보를 탐색하면서 문서를 계속 사용할 가능성이 높습니다.
장애물
이처럼 포괄적이고 상세한 프로젝트에는 항상 어려움이 따릅니다. 업계에서 신입 기술 문서 작성자로서 Sphinx와 ReST를 사용하여 문서를 작성한 경험이 제한적입니다. 또한 Matplotlib과 Git에 관해서도 초보자입니다. 이 네 가지 시스템을 다루고 공동작업 및 연구에 이를 익숙하게 사용하는 데는 시간이 걸립니다. 입문 단계 학습 과정에 필요한 토대를 마련하기 위해서는 커뮤니티 연결 단계 및 그 이전 단계에서 시간을 위임해야 합니다. 이 기간 동안 개념과 기본사항에 문제가 있는 경우 커뮤니티에 연락하여 추가 지원을 받아야 합니다.
시간대와 온라인 플랫폼 전반에서 공동작업을 조정하는 데도 약간의 조정이 필요합니다. 업계 전반에서 다양한 커뮤니케이션 채널을 사용하고 있으므로 모든 매체에서 쉽게 다가갈 수 있도록 하는 것이 중요합니다. 다양한 기대에 우선순위를 두는 방식을 투명하게 공개하겠습니다. 저는 업계에서 이와 같은 일을 막 시작했지만 책임감을 가지고 의견과 비판에 열려 있습니다. 이러한 자질은 어떤 분야에서나 가치 있다고 생각합니다.
또한 사용 편의성 테스트를 늘리는 것은 Matplotlib의 진입 경로에 도움이 될 것이라고 생각하는 문서 섹션입니다. 콘텐츠와 관련된 사용성 설문조사의 목적은 사용자 프로필(예: 캐릭터)을 제공하는 것입니다. 사용자 경험, 업계, 문제 해결 기록과 같은 정보는 가치가 있습니다. 이러한 요소는 절차의 언어를 형성하는 데 도움이 됩니다. 독자의 수준에 맞는 글을 쓰면 콘텐츠가 단순한 안내를 넘어 성숙해집니다.
사용성 테스트를 지속적으로 진행하는 데 큰 어려움을 겪는 경우가 많습니다. 콘텐츠 개발 중에 테스트를 진행하는 경우에도 테스트가 한 번만 이루어지는 경우가 너무나 흔합니다. 정기적인 사용성 테스트는 콘텐츠의 내러티브를 개선하는 데 도움이 됩니다. Matplotlib 커뮤니티와 함께 일정을 정하거나 반복적인 사용성 테스트를 진행하고 싶습니다.
결론
여가 시간에 Python과 Matplotlib을 사용해 본 경험이 약간 있습니다. 지난 몇 개월 동안 현재 문서와 호기심의 도움을 받아 스스로 배운 내용이 많습니다. 그 당시에는 제가 겪은 동영상과 멘토도 몇 개 있었죠. 관심 있는 프로그래밍 커리큘럼을 직접 만들면서 배울 것이 많고 개선의 여지도 많습니다.
Matplotlib과 커뮤니티에서 GSoD에 대해 제안한 아이디어를 확인한 후, 기술 문서 작성자로서 기술을 향상하고 배경에서 일하는 사람들로부터 더 많은 것을 배울 수 있는 좋은 성장의 기회가 될 것 같습니다. 이 Matplotlib 프로젝트는 의미가 있으며 제가 열정적으로 생각하는 이념이라고 생각했습니다.
사용 가이드를 정비하는 과정에서 테크니컬 라이터로서 제 목표는 사용자가 사용 가능한 기능에 부담을 느끼지 않고 원하는 작업을 할 수 있도록 돕는 것입니다. 최고의 문서는 계속해서 성장하고 사용자에게 적응하며 모든 사용자가 자신의 솔루션으로 이동할 수 있도록 허용해야 한다고 생각합니다.