이 페이지에는 Google Season of Docs에 선정된 기술 문서 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 조직:
- ESLint
- 기술 문서 작성자:
- Khawar
- 프로젝트 이름:
- 구성 문서 재구성/재작성
- 프로젝트 길이:
- 표준 기간 (3개월)
Project description
개요
이 프로젝트의 목표는 ESLint의 구성 문서를 재구성하고 효과적인 정보 아키텍처를 만드는 것입니다. 이렇게 하면 탐색이 쉬워지고 문서의 사용성과 유용성이 개선됩니다.
프로젝트 요약 현재 상태에서 ESLint의 구성 문서 (https://eslint.org/docs/user-guide/configuring)는 단일 페이지에 많은 정보를 제공합니다. 페이지에 제목, 부제목, 적절한 단락이 있음에도 문서가 너무 방대할 수 있습니다. 특정 섹션에 관심이 있는 사용자가 불편하게 느낄 수 있는 페이지의 특정 섹션으로 이동하는 방법은 없습니다. 또한 정보가 제대로 정리되지 않아 정보가 누락되어 목적을 달성하지 못하고 사용자에게 추가 작업을 요청할 수도 있습니다.
하지만 이러한 문제는 몇 가지 단계를 신중하게 따르면 해결할 수 있습니다. 이번 재구성의 첫 번째 단계로 콘텐츠 감사를 제안합니다. 콘텐츠 감사는 정보의 프레젠테이션에서 발생하는 문제를 파악하는 데 도움이 될 뿐만 아니라 콘텐츠 자체의 단점 (예: 오래되었거나 불완전한 정보)을 강조 표시합니다. 그런 다음 정보 아키텍처 (IA)를 만들어 지식 네트워크를 공개할 계획입니다. 이를 통해 다양한 주제에 따라 정보를 클러스터링하고 밀접하게 관련된 다양한 주제 간의 연결을 찾을 수 있습니다. 이러한 두 가지 방법을 통해 얻은 통계를 바탕으로 단일 페이지 문서를 여러 페이지로 나눕니다. 그러면 전체 패키지를 마크다운에서 연결하고 교차 참조할 수 있습니다. 그 결과 구성 문서가 더 잘 정리되고 탐색 및 이해하기 쉬워집니다.
동기 오랜 시간 동안 오픈소스 소프트웨어를 사용해 왔음에도 불구하고 제가 아는 것처럼 오픈소스 소프트웨어라는 용어에 익숙해진 지 얼마 안 됐습니다. edX를 통해 Python을 배우기 시작했을 때 사소한 오류가 얼마나 전체 코드를 망칠 수 있는지 궁금했습니다. 어떻게든 코드를 테스트하고 오류를 식별하는 것이 좋을 것 같아서 '린팅'이라는 용어를 알게 되었습니다. 아직 린팅 소프트웨어를 제대로 사용해 보지는 않았지만 앞으로는 린팅 소프트웨어를 사용하면 훨씬 더 쉽게 작업할 수 있을 것 같습니다.
전기 공학을 전공하고 프로그래밍 경험이 있어 코딩 문제와 프로그래머의 요구사항을 더 잘 이해할 수 있습니다. 또한 기술 및 프로페셔널 커뮤니케이션 석사 학위로 인해 사용자를 옹호하여 사람들의 삶을 더 편하게 만들기 위해 노력하고 있습니다. 제 기술과 전문 지식은 이 프로젝트에 적합하며 ESLint 문서에 가치를 더할 것입니다.
목표 이 프로젝트의 전반적인 목표는 ESLint 구성 페이지의 문서를 쉽게 이해할 수 있고 사용자가 부담스럽지 않도록 하는 것입니다. 프로젝트의 성공을 위해서는 콘텐츠를 쉽게 탐색할 수 있고 어떤 복잡한 요소도 없어야 합니다. 프로젝트의 중요한 목표는 다음과 같습니다. - 포괄적인 콘텐츠 감사 실시 - 정보 흐름을 파악하기 위한 정보 아키텍처 생성 - 문서를 재구성하기 위한 정보 아키텍처 개선 - 콘텐츠의 여러 섹션 간의 링크 및 참조 식별 - 재구성 요구사항을 충족하기 위해 필요한 경우 문서의 일부를 재작성/수정
- 콘텐츠가 유연하고 재사용 가능해야 함
프로젝트 설명 ESLint 구성은 중요한 기능으로, ESLint를 맞춤설정할 수 있습니다. 구성에 관심이 있는 사용자는 한 번에 한두 가지 측면에만 관심을 가질 가능성이 높습니다. 따라서 사용자에게 관심 있는 특정 주제를 안내하여 효율적인 방식으로 솔루션을 제공하는 것이 중요합니다. ESLint의 현재 구성 문서 상태는 많은 유용한 정보를 담고 있지만, 이 문서는 사용자가 부담감이나 좌절감, 상실감을 느낄 수 있도록 구성되어 있습니다. 예를 들어 ESLint에서 서드 파티 플러그인을 사용하는 방법을 알아보려는 경우 파서, 환경, 전역을 지정하는 방법에 관한 설명을 아래로 스크롤해야 합니다. 이러한 전체 과정은 사용자에게 피로감을 줄 수 있으며 웹사이트에서 멀어지게 할 수 있습니다. 마찬가지로 사용자가 페이지 중간에 있고 특정 섹션으로 이동하거나 유사한 주제를 살펴보려는 경우에도 이러한 지원이 제공되지 않으므로 쉽지 않을 것입니다. 문서의 초안이 얼마나 잘 작성되었든 문서의 품질은 유용성에 따라 달라지므로 이러한 문제는 즉시 해결해야 합니다. 다음 토론에서 이러한 문제와 기타 관련 문제에 대한 해결책을 제안합니다.
콘텐츠 감사 구성 문서를 재구성하는 프로세스의 첫 번째 단계는 포괄적인 콘텐츠 감사를 수행하는 것입니다. 감사는 오래된 콘텐츠, 중복, 누락된 콘텐츠 등 몇 가지 주요 문제를 파악하는 것을 목표로 합니다. 그 결과로 생성된 콘텐츠 감사 스프레드시트는 피드백을 위해 경영진 및 문서팀과 공유됩니다. 이는 문서를 체계화하고 제시하기 위한 새로운 전략을 세우는 데 도움이 될 것입니다.
정보 아키텍처 만들기 구성 문서의 지식 네트워크 또는 정보 흐름을 이해하려면 정보 아키텍처 (IA)를 만드는 것이 유용할 수 있습니다. 콘텐츠 감사 결과는 정보 흐름을 이해하고 개발하는 데 좋은 기반이 됩니다. 그런 다음 문서를 더 효과적으로 정리하고 표시하기 위해 개선된 버전의 IA가 생성됩니다. 개선된 IA를 사용하면 현재 콘텐츠의 구조를 재구성할 뿐만 아니라 문서의 여러 섹션 간의 링크와 포크를 식별하여 효율적인 네트워크를 만들 수 있습니다. 예를 들어 '규칙 구성'의 콘텐츠 다음에 '인라인 코멘트로 규칙 사용 중지'로 연결되는 링크가 올 수 있습니다. 이러한 다른 링크도 식별하여 문서의 서로 다른 섹션 간에 관계를 만들 수 있습니다.
목차 콘텐츠 감사 및 IA는 문서의 특정 섹션 및 하위 섹션으로 연결되는 링크가 포함된 세부적인 목차를 만드는 데 필요한 충분한 정보를 제공합니다. 각 섹션에 대해 별도의 파일을 만들고 다른 섹션에 적절한 참조를 추가하면 전체 문서 집합에 가치를 더할 수 있습니다. 구성 문서를 방문하는 사용자를 위한 목차를 만들 수 있어 웹사이트에 머무는 동안 사용자의 여정에 도움이 됩니다. 목차는 간단하면서도 포괄적일 수 있도록 모든 1차 및 2차 수준 제목을 포함할 수 있습니다. 예를 들어 Prettier (https://prettier.io/docs/ko/index.html)에서 문서를 구성하는 데 사용하는 방법이 있습니다.
모든 문서는 간단하고 잘 정리되도록 마크다운을 사용하여 작성됩니다. 문서는 향후 확장 및 변경될 수 있으므로 재사용할 수 있도록 특별히 주의합니다.
사용할 도구 프로젝트 작업 중에 유용할 수 있는 몇 가지 중요한 도구는 다음과 같습니다. - 필요에 따라 IA용 그림을 만들 수 있는 Draw.io - Markdown으로 문서를 작성하고 수정할 수 있는 Atom (또는 유사한 편집기)
- 문서의 버전 관리를 위한 GitHub
주요 목표proposal submission부터 project completion까지 다음의 잠정적인 주요 목표를 통해 프로젝트가 제때 완료되고 올바른 절차가 유지됩니다.
2020년 7월 10일~2020년 8월 16일: 제안서 검토 및 선택 ESLint 문서를 검토하고 프로젝트를 완료하는 데 필요한 기술 (예: Markdown 작성, GitHub에서의 공동작업)을 개발합니다. 또한 GitHub를 통해 문서에 기여하고 다른 사용자와 소통하여 문서를 더 잘 이해할 수 있도록 하겠습니다.
2020년 8월 17일~2020년 9월 13일: 커뮤니티 결속 커뮤니티 결속 기간에는 멘토 및 관련 팀과의 논의에 따라 제안서를 수정합니다. 필요한 경우 목표 및 주요 기록도 수정할 예정입니다. 또한 프로젝트 작업에 사용할 도구를 추려서 알려드리겠습니다.
2020년 9월 14일~2020년 9월 19일: 콘텐츠 감사 프로젝트를 시작하기 위해 구성 문서에 대한 포괄적인 콘텐츠 감사를 실시합니다. 콘텐츠 및 프레젠테이션의 문제를 강조하는 것이 목표입니다.
2020년 9월 20일~2020년 9월 25일: 정보 아키텍처 (IA) 콘텐츠 감사 후 구성 문서의 IA를 만듭니다. 이해하기 쉬운 방식으로 지식 네트워크를 제시하는 데 중점을 둘 것입니다. 이렇게 하면 정보 흐름을 개선하는 데 도움이 됩니다.
2020년 9월 26일~2020년 9월 30일: 링크 및 참조 이 단계에서는 IA를 분석하여 문서의 여러 섹션 간의 링크와 참조를 매핑합니다. 또한 모든 섹션의 계층 구조를 만들어 IA를 개선하겠습니다.
2020년 10월 1일~2020년 10월 3일: 최종 맵 콘텐츠 감사 및 IA를 통해 얻은 통계를 바탕으로 재구성된 구성 문서에 구현할 최종 맵을 만듭니다. 이 종합적인 지도에는 목차, 주제 계층 구조, 링크 및 문서 섹션 간의 상호 참조 목록이 포함됩니다.
2020년 10월 4일~2020년 10월 5일: 논의 이 시점, 즉 문서를 수정하기 전에 결과와 계획을 멘토와 관련 팀에 발표합니다. 이들의 의견은 계획을 다듬고 필요한 경우 수정하는 데 도움이 됩니다.
2020년 10월 6일~2020년 10월 20일: 재작성 및 수정 이 기간에는 작업이 필요한 문서 섹션을 수정하고 업데이트합니다. 구성 문서의 일부 섹션이 재작성되거나 새로운 내용이 추가될 수 있습니다. 이 단계에서는 문서가 정확하고, 최신 상태이며, 유연하고, 재사용할 수 있도록 하는 데 중점을 둡니다.
2020년 10월 21일~2020년 10월 25일: 수정 및 링크 이 단계에서는 문법 및 구조적 오류를 제거하고 작업의 정확성을 다시 확인하기 위해 내 작업을 검토합니다. 또한 문서가 앞서 고안된 지식 맵을 따르도록 IA에 따라 섹션 사이에 링크와 참조를 추가하겠습니다.
2020년 10월 26일~2020년 10월 31일: 제출 최종 버전 모든 마크다운 파일을 연결하고 목차를 만든 후 초안을 멘토와 공유해 드리겠습니다. 이 파일은 전체 패키지 형식의 초안 제출물로 사용됩니다.
2020년 11월 1일~2020년 11월 5일: 첫 번째 검토 이 5일 동안 멘토와 함께 초안을 논의합니다. 부모님께서 피드백을 받고 제 아이디어에 대해 함께 논의하여 수정이 필요한 수정 목록을 작성하겠습니다.
2020년 11월 6일~2020년 11월 12일: 첫 번째 수정 멘토의 의견을 반영하여 문서의 첫 번째 초안을 수정하겠습니다. 실제 수정은 댓글과 의견의 특성에 따라 달라지지만 재사용, 정확성, 유연성의 목표가 편집 단계의 중심 역할을 합니다.
2020년 11월 13일~2020년 11월 15일: 두 번째 검토 초안 수정을 마친 후 진행 상황을 멘토와 관련 팀에 다시 한번 논의합니다. 이 논의에서는 첫 번째 버전에 적용된 수정사항에 중점을 두고 수정 과정에서 발생할 수 있는 다른 문제도 강조 표시합니다.
2020년 11월 16일~2020년 11월 19일: 두 번째 수정 작업 이후 4일 동안 문서를 수정합니다. 그 결과 제작된 버전은 최종적으로 수정하기 위해 멘토와 논의됩니다. 이 단계가 완료되면 문서는 최종 형태로 완성되어 웹사이트와 GitHub 저장소에 업로드할 수 있습니다.
2020년 11월 20일~2020년 11월 23일: 웹사이트에 업로드 필요한 모든 수정이 완료되면 문서가 웹사이트에 업로드됩니다. 문서 작업을 마치기까지 며칠이 남아 있으므로 이 과정에서 발생하는 문제는 적절하게 처리됩니다.
2020년 11월 24일~2020년 11월 28일: 프로젝트 보고서 이 5일 동안 프로젝트에 관한 자세한 보고서가 작성됩니다. 제시된 목표, 어려움, 문제, 해결책은 프로젝트 보고서의 일부가 됩니다. 보고서는 의견을 받기 위해 멘토와 공유됩니다.
2020년 11월 29일~2020년 11월 30일: 최종 제출 모든 파일과 함께 프로젝트 및 프로젝트 보고서가 멘토에게 제출됩니다. 전체 프로젝트 검토는 멘토 및 관련 팀과의 회의/토론을 통해 진행됩니다.
프로젝트 전반에 걸쳐 멘토의 귀중한 의견을 얻기 위해 계속 컨설트할 예정입니다. 이러한 모든 마일스톤은 커뮤니티 결속 및 제안서 검토 기간에 멘토와의 논의를 바탕으로 변경될 수 있습니다.
약력 노스캐롤라이나 주립대학교에서 전기 공학 학사 학위와 기술 및 전문 커뮤니케이션 석사 학위를 받았습니다. 기술 및 전문 글쓰기 및 편집, 커뮤니케이션 및 콘텐츠 관리, 웹 및 모바일 사용성 연구, 교육 설계 분야에서 경험이 있습니다. 온라인 간행물 (Global Village Space)의 부편집자와 Duke University의 Duke Forge에서 커뮤니케이션 인턴으로 근무했습니다. 그 외에도 창작 문학에도 관심이 있습니다.