이 페이지에는 Google Season of Docs에서 승인된 테크니컬 라이팅 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 조직:
- 크리에이티브 커먼즈
- 테크니컬 라이터:
- 니미슈니브
- 프로젝트 이름:
- 어휘 사용 가이드
- 프로젝트 기간:
- 표준 기간 (3개월)
Project description
프로젝트 개요
Vocabulary는 웹사이트 구축을 위한 기본 UI 구성요소 라이브러리로 사용할 수 있는 엄청난 잠재력을 가지고 있습니다. 하지만 강력하면서도 일반인 친화적인 안내 가이드가 필요합니다. 구성요소 가이드, 사용 사양 및 구성 변경과 같은 중요한 개발자 정보는 모든 문서의 필수 부분을 형성합니다. 이를 통해 기존 사용자가 어떻게 어휘가 어떻게 계속 성장하고 새로운 성과에 도달하는지 느낄 수 있게 될 뿐만 아니라, 상대적으로 최신 프로젝트에서도 어휘의 사용을 촉진할 수 있습니다. 인턴으로 근무하면서 원하는 결과를 얻기 위해서는 기존 구성 요소 사용에 대한 실용적 가이드를 작성하는 것뿐만 아니라 어휘, 어휘, 글꼴에 관한 홈페이지 (각각 통합 문서로 유도)를 설계하고 개발하는 것이 포함될 것입니다.
프로젝트 계획
문제: 문서는 특정 오픈소스 라이브러리의 성공을 결정하는 주된 이유 중 하나입니다. 개발자가 애플리케이션을 빌드하는 데 적합한 기술 스택을 선택할 때 떠오르는 주요 질문은 '라이브러리가 잘 문서화되어 있는가? 잘 관리되고 있는가? 상당한 사용과 오류 지원이 있는가?'라는 질문을 던집니다. 이 질문은 이 프로젝트 아이디어를 구상하는 동안 스스로에게 물어봐야 할 질문입니다. 소프트웨어 엔지니어링의 관점에서 볼 때,
요구사항 분석: 간결하고 통합된 문서가 반드시 필요합니다. 문서화의 부족은 오픈소스 애플리케이션에 대한 미래 관점에 악영향을 미치며, 이는 매우 중요한 구성요소이며 무시할 수 없습니다. 이러한 문서로 연결되는 링크를 제공하면 시청자의 관심을 순식간에 포착할 수 있는 매력적인 홈페이지여야 합니다. 또한 문서가 잘 정리되어 있어 원활하게 진행할 수 있어야 합니다.
사양: 요구사항에 따라 사양이 결정될 수 있습니다. 문서의 내용은 semantic-ui, scikit-learn, numpy, 부트스트랩 등의 잘 알려진 문서에서 얻은 몇 가지 아이디어와 함께 CC netlify 웹사이트에 있는 데이터로 구성될 수 있습니다. 이 작업의 출력물은 필수 방문 페이지와 전체 문서 가이드입니다.
현재 어휘, 뷰-어휘, 글꼴과 관련된 몇 가지 일반적인 문제는 다음과 같습니다.
이러한 자료는 전혀 없습니다. 문서가 있더라도 일부는 Netlify 웹사이트에 여기저기 흩어져 있습니다. 그렇다고 해서 사용자, 개발자 또는 외부 참여자가 Google 라이브러리를 사용할 수는 없습니다.
특정 구성요소로 이동하여 해당 코드를 복사하려면 추가 클릭이 필요합니다. '탭 구성요소 CC 어휘'와 같은 간단한 Google 검색으로는 원하는 정보가 반환되지 않습니다. 문서 가이드의 검색 옵션을 사용하면 UX가 크게 개선됩니다.
구성요소에 관한 좀 더 자세한 텍스트 설명으로 명확하지 않은 세부정보를 설명합니다.
실시간 실행 옵션이 없습니다. 실시간 실행은 JSFiddle과 같은 다양한 사이트에서 지원됩니다. 이를 통해 개발자는 전체 애플리케이션을 실행하지 않고도 구성 요소를 파악할 수 있습니다.
해결 방법
여러 가지 솔루션이 있습니다. 하지만 여기서 몇 가지만 다루고 결론 부분에서 최종 해결책을 제시하겠습니다.
readthedocs는 오픈소스 라이브러리용 문서를 작성하는 잘 알려진 솔루션입니다. 이 도구는 Python 문서 도구인 Sphinx를 기반으로 합니다.
장점:
- 이더리움 (Solidity)과 같은 조직에서 널리 사용되는 문서 생성 방식입니다.
- 최적으로 구조화된 문서.
- 무료 정적 호스팅
단점:
- 스타일을 완전히 제어할 수 없습니다.
= Sphinx 사용 Sphinx는 문서 부분에도 기본적으로 사용할 수 있으며 모든 목적에 적합한 기능을 제공합니다.
장점:
- 문서 작업에 가장 많이 사용되는 Python 도구입니다.
- 문서 검색도 지원합니다.
- 기본 CSS는 사용자설정 CSS로 재정의할 수 있습니다. 일부 CSS는 .rst 파일을 사용하여 HTML을 관리합니다.
단점:
- 추천 프로젝트 언어와는 다른 Python 및 재구성된 텍스트 형식 (.rst)으로 코딩하는 작업이 수반될 수 있습니다.
= Jekyll 테마 사용 Jekyll 테마는 github 페이지에 통합되어 있으며 필요에 따라 맞춤설정할 수 있는 기존 템플릿이 미리 준비되어 있습니다.
장점:
- 모든 목적을 위해 준비된 문서 테마.
- 기본 CSS 및 스타일은 맞춤 스타일로 재정의할 수 있으며 HTML도 제어할 수 있습니다.
- 페이지 빌드를 위한 기본 Primer CSS를 가져옵니다.
- GitHub 페이지와의 간편한 통합
단점:
- 최상의 문서 구조를 제공하지 못할 수도 있습니다.
=GitHub 페이지 사용하기 정적 사이트 (HTML, CSS, JS) 구축을 위한 표준 github 페이지.
장점:
- 문제의 거의 모든 항목을 완벽하게 제어할 수 있습니다.
- 레이아웃, 색상 및 스타일을 최대한 유연하게 결정할 수 있습니다.
- 어휘 구성요소를 간편하게 사용
- 코드 스니펫과 실시간 실행 링크를 간편하게 삽입
단점:
- 이 방법은 시간이 더 오래 걸릴 수 있습니다.
= Haroopad 사용 대신 대체 마크다운 솔루션을 제공합니다.
장점:
- 최소한의 충만한 코딩이 수반될 수 있습니다.
- 문서를 완벽하게 작성하는 데 중점을 둡니다.
단점:
- CSS에 대한 제어력 부족
- 커뮤니티에서 최상의 지원을 받을 수도 있고 그렇지 않을 수도 있습니다.
- MDX가 지원되지 않을 수 있습니다.
= MKDocs 사용 대신 또 다른 대체 마크다운 솔루션을 제공합니다.
장점:
- 최소한의 충만한 코딩이 수반될 수 있습니다.
- 더 많이, 더 적게 코딩합니다.
단점:
- CSS에 대한 제어력 부족
- 커뮤니티에서 제공하는 지원이 충분하지 않을 수 있습니다.
- Python을 사용합니다. Amazon S3 인스턴스를 가동해야 할 수도 있습니다.
= VueJS +StorybookJS 사용 이 접근 방식은 어휘와 자매 저장소에서 흔히 사용됩니다.
장점:
- 과거의 업무 경험을 감안할 때 문제없이 작동할 것이 보장되는 기술 고수
- 코드베이스에 관한 지식.
- 이 분야에는 유능한 기술이 없습니다.
단점:
- 같은 목적을 위해 더 간단한 옵션이 있을 수도 있습니다.
결론적으로, 저는 VueJS+Storybook 접근 방식 (HTML,CSS,JS)을 수반하는 접근 방식이 익숙하다는 점을 고려할 때 이 접근 방식이 가장 적합하다고 생각합니다. 하지만 이는 이 애플리케이션을 개발하는 데 있어 Google이 완전히 나아지지 않을 것임을 의미하기도 합니다. CC-Vocabulary 구성요소를 사용하는 것도 매우 간단합니다. 하지만 이 문서의 구조를 결정하기 위해서는 readthedocs 문서의 부제목으로 콘텐츠가 나뉘는 방식을 확실히 고려해야 합니다. StoryBook을 사용하는 시맨틱 UI 웹사이트는 미니멀한 디자인으로 단 몇 번의 클릭만으로 사용자가 원하는 것을 쉽게 알 수 있다는 점에서 깊은 인상을 받았습니다. 시맨틱 UI 외에도 Material Design, Primer, Bootstrap, Carbon Design 등 작업을 위한 UI 스타일 지정 가이드와 디자인 시스템으로 사용하기 위한 방법도 살펴봤습니다. 또한 미리 준비된 Jekyll 문서 테마에서 이에 대한 영감을 얻을 수도 있습니다.