이 페이지에는 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 문서를 통합하는 것이 TikZ 사진을 HTML (예: TeX4ht)에 삽입하기 위한 다양한 패키지와 수정사항으로 인해 큰 문제가 되지 않는 것으로 보입니다.
예를 들어 Overleaf (공동작업을 용이하게 하고 인스턴트 미리보기를 제공)와 내가 제공할 사전 정의된 템플릿을 사용하면 SciPy 내에서 향후 가이드를 유지관리하는 문제를 쉽게 해결할 수 있습니다. 기본적으로 그래픽 가이드는 서로 크게 다르지 않습니다. 구조, 색상 팔레트 및 모양은 거의 변하지 않으므로 나중에 형태를 변경하거나 추가로 맞춤설정해도 문제가 되지 않습니다.
(제안의 전체 버전은 공유된 GSoD 폴더에서 확인할 수 있습니다.)