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