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