이 페이지에는 Google Season of Docs에 선정된 기술 문서 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 구성:
- SciPy
- 기술 문서 작성자:
- mkg33
- 프로젝트 이름:
- 사용자 중심 문서 및 철저한 구조 조정
- 프로젝트 길이:
- 표준 기간 (3개월)
Project description
동기:
다양한 요구사항을 가진 사용자가 쉽게 액세스할 수 있도록 기존 문서를 리팩터링할 계획입니다. 연구원은 고급 기능과 미묘한 기능에 관심이 있을 가능성이 높고, 전문 지식이 없는 사용자는 단계별 가이드와 다이어그램을 선호한다는 것은 말할 필요도 없습니다.
저는 개인적인 이유와 전문적인 이유로 이 프로젝트를 진행하고자 합니다. 첫째, SciPy를 통해 많은 도움을 받았기 때문에 SciPy에 크게 기여하고 싶습니다. 둘째, 다른 소프트웨어에서 문서가 불충분하거나 누락된 경우가 너무나도 자주 발생하며, 사용자에게 철저한 가이드가 제공되었다면 코드 사용 방법을 얼마나 더 빠르게 배울 수 있을지 항상 궁금합니다.
목표:
기존 SciPy 문서를 콘텐츠와 그래픽 측면에서 모두 개선하는 것을 목표로 합니다. 이 문제에 대한 제 접근 방식에서 가장 중요한 특징은 사용자 설문조사를 배포하고 분석하는 것입니다. 즉, 온라인에서 간결한 설문조사를 실시하여 다양한 사용자가 문서와 관련된 요구사항을 제기할 수 있도록 합니다. 사용자의 의견은 영감의 원천이 되어야 한다고 생각합니다. 그렇지 않으면 더 사용자 친화적인 문서를 작성할 수 없을 것입니다.
프로젝트 자체의 실현과 관련하여 첫 번째 단계에서는 사용자 설문조사를 설계하고 분석하는 동시에 현재 문서에서 발견한 몇 가지 스타일 관련 문제를 해결할 예정입니다. 예를 들어 일관성이 없거나 (예: 2차원 배열과 함께 2차원 배열이 발생함) 재작성해야 하는 복잡한 문장 또는 특정 하위 페이지에 알파벳 순서가 없는 경우 등이 있습니다. 두 번째 단계에서는 설문조사 결과 및 기타 커뮤니티 요청을 바탕으로 관련 주제에 대한 하이퍼링크가 포함된 그래픽 가이드를 도입하는 데 중점을 둘 예정입니다. 장기적으로는 다양한 사용자에게 맞춤화된 만족스러운 문서를 제공하고자 합니다. 또한 언어적 및 구조적 측면에서 더 일관된 튜토리얼을 제공하기 위해 노력하겠습니다. 마지막으로, 현재 커뮤니티의 요구사항에 따라 새로운 튜토리얼을 작성할 계획입니다.
사용자 설문조사:
사용자 설문조사와 관련하여 몇 가지 이유로 Google Forms를 사용하는 것이 좋습니다. 우선 Google Forms는 무료이며 응답자 수, 질문 수 등과 관련하여 무제한의 기능을 제공합니다. 또한 매력적인 시각적 양식, 가장 유용한 설문조사 옵션(예: 맞춤설정 가능한 선형 눈금자, 체크박스, 객관식)을 제공하며, 무엇보다도 통계 분석을 위해 결과를 쉽게 내보낼 수 있습니다. 온라인 조사에 따르면 적어도 현재로서는 Google Forms가 설문조사를 진행하는 데 가장 적합한 무료 도구인 것으로 보입니다. 좀 더 가벼운 주제로 말하자면 Google에서 운영하는 이니셔티브에서는 Google 제품을 사용하는 것이 좋습니다.
샘플 질문이 포함된 예비 설문조사를 만들었습니다 (https://docs.google.com/forms/d/e/1FAIpQLSeBAO0UFKDZyKpg2XzRslsLJVHU61ugjc18-2PVEabTQg2_6g/viewform에서 액세스할 수 있음). 최종 버전의 적절한 질문 수는 10~15개여야 합니다. 구체적인 결과를 얻으려면 주로 객관식 질문, 선형 눈금자, 체크박스를 사용하는 것이 좋습니다. 선형 척도는 전체 스펙트럼과 유사해서는 안 됩니다. 혼란을 야기할 뿐이며 결과에 높은 분산이 발생할 수 있습니다. 개방형 질문은 최대 2개여야 합니다. 그렇지 않으면 결과가 매우 분산되어 전혀 도움이 되지 않습니다. 통계 소프트웨어를 사용하여 데이터를 쉽게 내보내고 자동으로 분석할 수 있으므로 응답 수가 많아도 문제가 되지 않을 것으로 생각됩니다. 응답 수가 실제로 매우 많다고 가정하면 주관식 질문을 분석하는 데 약간의 시간이 걸릴 수 있지만 부담스러운 수준은 아닐 것으로 생각됩니다. 결국 일반 사용자는 문서의 상태에 관한 에세이를 작성할 가능성이 낮습니다. 최악의 경우 일부 답변은 향후 분석을 위해 저장될 수 있습니다.
그래픽 가이드:
탐색 도구로 사용하기 위한 그래픽 가이드에 대한 제 비전은 (대부분의) 인간이 순수한 텍스트 기반 정보보다 직관적인 시각적 구조를 더 잘 처리한다는 일반적인 전제에 기반합니다. 또한 유사한 관심 주제를 선으로 연결하는 주제 중심의 다이어그램은 경험이 부족한 사용자뿐만 아니라 모든 사용자에게 매우 유용한 정보입니다.
구현 세부정보와 관련하여 TikZ 패키지를 사용하는 것이 좋습니다. 무엇보다도 이 도구는 강력하며 곧 지원 중단될 위험이 없어 보입니다. 또한 고품질 출력을 제공하고, 매우 탄탄한 문서가 있으며, TeX StackExchange 및 기타 주류 포럼에서 자주 다루는 주제입니다. 가장 중요한 것은 TikZ 파일 (더 정확하게는 그 안에 있는 수많은 하이퍼링크)을 HTML 문서와 통합해도 큰 문제가 되지 않는다는 것입니다. HTML에 TikZ 그림을 삽입하기 위한 다양한 패키지와 수정사항 (예: TeX4ht)이 있기 때문입니다.
예를 들어 SciPy 내에서 가이드를 유지관리해야 하는 문제는 Overleaf (협업을 지원하고 즉각적인 미리보기 제공)와 제가 제공할 사전 정의된 템플릿을 사용하면 쉽게 해결할 수 있습니다. 기본적으로 그래픽 가이드는 서로 크게 다르지 않습니다. 구조, 색상 팔레트, 도형은 거의 변하지 않으므로 후속 도형 재구성 및 추가 맞춤설정은 문제가 되지 않습니다.
공유 GSoD 폴더에서 전체 버전의 제안서를 확인하세요.