이 페이지에는 Google Season of Docs에 선정된 기술 문서 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 조직:
- gRPC-Gateway
- 테크니컬 라이터:
- iamrajiv
- 프로젝트 이름:
- gRPC-Gateway의 기존 문서 사이트 리팩터링
- 프로젝트 길이:
- 표준 기간 (3개월)
Project description
개요:
사용자 문서 사이트는 최종 사용자가 제품 또는 서비스를 사용하는 데 도움을 주기 위해 만들어졌습니다. 우수한 사용자 문서 사이트는 사용자가 소프트웨어 사용 방법, 기능, 도움말 및 유용한 정보를 배울 수 있는 경로를 제공하고 소프트웨어 사용 시 자주 발생하는 문제를 해결할 수 있는 경로를 제공하므로 매우 중요합니다. 또한 지원 비용을 줄이고 제품의 기업 이미지에 포함됩니다. 우수한 사용자 문서 사이트는 제품과 개발자팀의 건전성을 보여주는 신호입니다. 우수한 사용자 문서 사이트가 없으면 사용자가 위의 작업을 효과적이고 효율적으로 수행하는 방법을 알지 못할 수 있습니다. 사용자 문서 사이트는 제품의 성공을 보장하는 데 중요한 역할을 할 수 있습니다. 효과적인 커뮤니케이션은 항상 모든 비즈니스 또는 제품의 핵심이며 우수한 문서는 이러한 커뮤니케이션을 모든 사용자가 성공을 위해 액세스할 수 있는 관리 가능한 프레임워크에 담아냅니다.
이 글을 쓰는 시점을 기준으로 gRPC-Gateway 저장소는 약 1, 200번 포크되었으며 184명이 이 저장소에 참여했습니다. 이는 전 세계 많은 사람들이 gRPC-Gateway를 사용하고 있으며 gRPC-Gateway 사용 방법에 대한 안내를 위해 해당 사용자 문서를 읽어보는 것이 좋습니다. 그러나 gRPC-Gateway 사용자 문서 및 문서 사이트는 현재 오래되고 불완전하며 gRPC-Gateway 커뮤니티는 이 프로젝트를 사용하여 기존 문서 사이트를 리팩터링하고 문서 사이트를 개선하여 최종 사용자가 gRPC-Gateway를 사용할 때 원활한 환경을 제공하고자 합니다.
현재 상태:
현재 gRPC-게이트웨이 문서 사이트에는 다음과 같은 두 가지 주요 문제가 있습니다.
• 첫 번째 문제는 사용된 사이트 및 테마의 스타일과 구조가 오래되고 불완전하며 탐색하거나 정보를 찾기 어렵고 우수한 문서 웹사이트의 많은 기능을 다루지 않는 잘못되고 오래된 문서 웹사이트입니다. gRPC-게이트웨이의 기존 문서 사이트를 리팩터링하는 작업에는 웹사이트 스타일 지정, 문서 검색 등의 기능 추가, 웹사이트의 UI 개선, 적절한 사이드바에 튜토리얼과 예시 정리, 새 플로 차트 및 이미지 설계 등을 통해 기존 플로 차트와 이미지 업데이트 등이 포함됩니다. 이러한 작업은 저의 기본 목표가 될 것이며, 제 작업은 기존 문서 사이트의 스타일 지정과 재구성에 더 기반할 것입니다.
• 두 번째 문제는 gRPC-Gateway의 기존 문서, 튜토리얼, 예시 등을 리팩터링해야 한다는 점입니다. 이는 파일에서 맞춤법 및 문법 오류를 삭제하고, Go 스니펫을 올바르게 정렬하고, Gofmt 형식에 따라 Go 스니펫을 리팩터링하여 해결할 수 있습니다. 또한 이 경우 필요한 경우 문서, 튜토리얼, 예시를 추가하거나 리팩터링 후 기존 파일을 재사용할 수 있습니다. 이는 부차적인 목표이며 기존 Docs 사이트의 스타일 지정 및 구조 조정이라는 기본 목표를 완료한 후에 진행할 예정입니다.
내가 제안한 문서 사이트가 현재 문서보다 개선되었다고 생각하는 이유는 무엇인가요?
제안된 사용자 문서 웹사이트는 최종 사용자를 위해 효율성, 일관성, 안전을 개선하고 보장하도록 구성될 것입니다. 또한 작성된 가이드와 관련 플로우 차트 및 이미지가 포함되어 있으며, 섹션과 기능이 잘 디자인되어 더 나은 디자인과 UI를 제공합니다.
gRPC-Gateway 문서에서 메서드와 예시를 자세히 설명합니다. 하지만 여전히 이전 Jekyll 테마를 사용하고 있으며, 요즘은 더 나은 SSG (정적 사이트 생성기) Jekyll 테마가 있습니다. 또한 페이지를 재구성하고 새로운 예시와 튜토리얼을 추가하고 이전 콘텐츠를 업데이트 및 재작성하여 사용자에게 더 유용하게 만들어야 합니다.
제안된 목표 및 아이디어의 구조와 로드맵:
이 프로젝트의 주요 목표:-
위의 목표와 아이디어는 다음과 같은 방법으로 구현할 수 있습니다.
현재 Jekyll 테마를 더 나은 강력한 테마로 전환합니다. Jekyll 테마를 다시 사용하는 이유는 유지보육자가 이미 새 Jekyll 테마와 유사한 기존 Jekyll 프레임워크와 테마를 알고 있으므로 프로젝트의 워크플로에 쉽게 기여하고 이해할 수 있기 때문입니다.
인터넷에서 다양한 Jekyll 테마를 살펴본 결과, 다음과 같은 기능으로 인해 gRPC-Gateway 문서 사이트에 가장 적합한 테마 모음은 https://idratherbewriting.com/documentation-theme-jekyll/ 테마 모음입니다.
• Markdown:- 기술 문서 작성자가 설치에 관해 걱정할 필요가 없습니다. .md 파일에 간단히 작성할 수 있습니다. 누구나 웹사이트에 표시된 수정 버튼 (새로운 기능)을 클릭하고 기여 (GitHub 페이지의 변경사항 수정/제안)를 통해 기능을 개선할 수 있습니다. 이렇게 하면 사용자가 새 콘텐츠를 추가하거나 콘텐츠를 수정하여 개선하도록 참여하게 됩니다.
• 문서 검색:- 사용자가 관련 콘텐츠를 쉽고 빠르게 찾을 수 있도록 검색창이 있어야 합니다.
• 댓글 섹션:- 사용자는 게시물 및 튜토리얼에 댓글을 달고 의견을 공유할 수 있습니다. 프로젝트 문서에 대한 다른 사용자의 의견을 읽을 수 있습니다.
• 새로운 출시 노트 및 블로그:- 현재 개발 및 로드맵에 관한 새로운 블로그 게시물과 뉴스로 웹사이트를 업데이트해야 합니다. 따라서 방문 페이지에 일종의 블로그가 있어야 합니다.
• 빠른 개발:- 대부분의 SSG (정적 사이트 생성기) 프레임워크는 서버에서 실행되며 파일의 변경사항이 UI에 즉시 반영됩니다. 또한 배포 및 빌드 프로세스도 간단해야 합니다. 향후 프레임워크를 변경하려면 다음을 사용합니다. 그러면 쉽게 할 수 있습니다. 대부분의 프레임워크는 마크다운 작성을 지원하므로 .md 파일을 이동하면 몇 가지 변경만으로도 충분합니다.
여기서는 기존 웹사이트 페이지를 새 웹사이트 섹션 및 페이지로 분할하고 있습니다.
• 방문 페이지:-
방문 페이지는 gRPC-Gateway의 주요 기능을 설명해야 합니다.
- gRPC-Gateway 시작하기 (사용자 가이드로 리디렉션)
- 간단한 설치 안내 (간단한 명령어)
- gRPC-Gateway를 사용하는 이유
- gRPC-Gateway를 사용하는 프로젝트
따라서 기본적인 생각은 긴 설명을 작성하는 대신 방문 페이지에 주요 사항을 표시하고 세부정보로 이동할 수 있는 링크를 제공하는 것입니다.
• gRPC-Gateway 사용자 가이드 페이지:-
- 설치 가이드
- gRPC-Gateway를 사용한 빠른 시작
• gRPC-Gateway 개발자 가이드 페이지:-
개발 가이드, 참여 가이드, Git 설정, 윤리 강령, 문서 설정, 개발 워크플로 등이 내부에서 유사한 페이지를 가리킵니다. 따라서 모든 파일을 리팩터링하고 재정렬해야 합니다. 기본 개발 페이지에는 이러한 페이지가 모두 포함되어야 하며 각 단계에서 하이퍼링크가 생성됩니다.
• gRPC-Gateway 정보 페이지:-
모든 참여자의 목록이 팀 섹션에 표시되어야 합니다. 빠른 링크 및 출시 노트, 최신 블로그가 추가되어 사용자가 현재 gRPC-Gateway 뉴스를 읽도록 유도합니다.
• 블로그, 릴리스 노트 및 튜토리얼 페이지:-
웹사이트에 블로그 옵션이 있어야 한다고 생각합니다. 따라서 뉴스와 출시 소식을 쉽게 전달할 수 있습니다. 튜토리얼 페이지에는 gRPC-Gateway API 및 개념을 명확히 설명하는 인기 있는 강연 및 도움말이 포함됩니다. 참여자는 튜토리얼 페이지에 튜토리얼 링크를 추가할 수 있습니다.
위 작업을 완료한 후 v2 브랜치에서 동일한 변경사항을 업데이트하고 gRPC-Gateway의 마스터 브랜치와도 동일하게 만듭니다.
이 프로젝트의 부차적인 목표:-
gRPC-Gateway 문서를 더 강력하고 읽기 쉽게 만들기 위해 다른 변경사항도 적용해야 합니다.
• gRPC-게이트웨이의 모든 기존 파일에서 문법, 오타 수정, 사이트에서 링크와 게시물 정리 및 정렬
• 대부분의 기능에 AWS, 배경, 사용 등에 관한 사이트의 문서 섹션과 같이 매우 짧은 문서가 있으므로 필요한 경우 gRPC-Gateway에 문서와 콘텐츠를 추가합니다.
• Gofmt 형식에 따라 Go 스니펫 gRPC-Gateway 리팩터링
위 작업을 완료한 후 v2 브랜치에서 동일한 변경사항을 업데이트하고 gRPC-Gateway의 마스터 브랜치와도 동일하게 만듭니다.
이 프로젝트에 적합한 이유:
제가 이 프로젝트에 적합한 이유는 다음과 같습니다.
• 조직의 문서를 개선한 경험이 있으며 모든 버전 제어 시스템을 사용할 수 있으므로 GitHub에서 명령을 실행하는 데 문제가 없습니다. • 또한 사람들에게 가치를 창출하는 프로젝트에 참여하는 것이 저의 원동력입니다. 누군가 최대한 효율적인 방법으로 작업을 하도록 하려면 문서화해야 한다고 생각합니다. 프로세스를 문서화하면 관련된 모든 사용자에게 효율성, 일관성, 안심할 수 있는 환경을 제공할 수 있습니다. • 지난 두 달 동안 gRPC-Gateway에 참여하고 11개의 PR을 병합한 이후로 gRPC-Gateway의 워크플로 및 코드베이스에 익숙합니다.