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