이 페이지에는 Google Season of Docs에서 승인된 테크니컬 라이팅 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 조직:
- Cloud Native Computing Foundation (CNCF)
- 테크니컬 라이터:
- 스리티
- 프로젝트 이름:
- SMI 및 관련 서비스 메시 문서 개선
- 프로젝트 기간:
- 표준 기간 (3개월)
Project description
서비스 메시 기술은 기본적으로 모든 보안, 관리, 모니터링 요구사항을 처리하여 증가하는 서비스 수에 가치를 제공하는 것을 목표로 합니다. 서비스 메시 인터페이스 (SMI)는 가장 일반적인 서비스 메시 사용 사례 (트래픽 정책, 원격 분석, 이동)에 대한 API 집합을 정의하고 마이크로서비스 환경에서 서비스 간 통신을 처리하기 위한 전용 인프라 레이어인 서비스 메시 간의 호환성을 지원합니다. 이러한 인터페이스를 표준화하면 향상된 최종 사용자 환경이 제공되므로, 이는 SMI 및 관련 서비스 메시의 향후 목표가 될 것입니다.
현재 상태:
사용자 가이드: SMI는 비교적 새로운 샌드박스 프로젝트로 2020년 4월에 CNCF에 기부되었습니다. 따라서 최종 사용자 문서에 프로젝트가 없습니다. Meshery는 다양한 서비스 메시의 성능 채택, 구성, 운영, 관리를 용이하게 하고 모든 서비스 메시를 기반으로 실행되는 애플리케이션의 측정항목 수집 및 표시를 통합하는 모든 종류의 서비스에 대한 성능 벤치마킹 기능이 있는 서비스 관리 영역입니다. 따라서 전체 SMI 사용자 커뮤니티의 출발점이 될 메시에 대한 가이드부터 시작하려고 합니다.
사용자 튜토리얼: 기존 SMI 플랫폼 중에서도 Meshery는 SMI와 관련 서비스 메시의 이점과 사용법을 보여주는 완벽한 애플리케이션이므로 제가 SMI 기능을 보여주는 기본 도구로 사용하려고 합니다.
API 문서: 현재 존재하지 않습니다. SMI와 다양한 관련 프로젝트의 API 엔드포인트는 플랫폼에 정의되어 있습니다. 일례로 Meshery는 server.go (https://github.com/layer5io/meshery/blob/master/router/server.go)에 엔드포인트가 정의되어 있지만 외부에서는 충분한 의견이 작성되지 않았거나 문서화되어 있지 않습니다. 이 문제는 API에 관한 의미 있는 문서로 해결할 수 있으며 사용자가 엔드포인트를 테스트하고 기능을 미리 볼 수 있는 방법을 추가하여 개선할 수 있습니다.
분석:
사용자 튜토리얼은 사용자가 소프트웨어를 이용하고 테스트를 실행할 수 있도록 제작되었습니다. 광고는 사용자의 관심을 사로잡을 수 있도록 상호작용적이고 심미적으로 매력적이어야 하며 무엇보다도 사용하기 쉬워야 합니다.
하지만 사용자 가이드를 작성하거나 호스팅하는 경우 사용자 가이드가 참조 가이드 또는 문제를 빠르게 해결할 수 있는 공간으로 사용되는 경우가 많으므로 보다 성숙한 형식을 사용하는 것이 좋습니다. 이러한 앱은 상호작용하기보다는 체계적으로 구성되고 명확성, 일관성, 우수한 사용자 플로우를 개선하는 데 초점을 맞춰야 합니다.
이를 위한 가능한 해결책은 Jekyll의 도움을 받아 Google Codelabs와 독립적인 사용자 가이드를 사용하여 별도의 사용자 튜토리얼을 만들고 마지막으로 API 문서와 함께 통합하여 최종 사용자와 미래의 공동작업자 모두에게 균형 잡힌 경험을 제공하는 것입니다.
대상: SMI 프로젝트는 모든 프로젝트에 배포 및 운영 관행, 학습 환경 및 성능 벤치마크를 제공합니다. 개인과 조직 모두에 적합합니다.
사용자 가이드: 사용자 측에서 기존 IT 지식을 추정하지 않고 초보 사용자를 타겟팅할 것입니다. 대상: 초보자용 사용자 이유: 주로 방대한 참조 가이드로 사용되며 시간이 지나면서 업데이트해야 합니다. 여기에는 사용자가 서비스 메시를 설정하고 사용하는 데 필요한 모든 정보를 얻을 수 있도록 자세한 설명과 유용한 팁이 포함됩니다. 필요할 때마다 동영상, 사진, 스크린샷, GIF를 추가하여 가이드의 참여도와 사용자 친화도를 높일 수 있습니다.
사용자 튜토리얼: 대상: 초보자용 사용자 이유: 사용자의 관심을 끌고 소프트웨어 테스트를 원활하게 실행하여 서비스 메시 인터페이스를 더 잘 이해할 수 있도록 튜토리얼을 흥미롭고 심미적으로 매력적으로 만드는 데 중점을 둡니다.
API 엔드포인트 문서: 대상: 고급 사용자 이유: 이 섹션에서는 기본적인 IT 지식 수준을 가진 고급 사용자를 위해 서비스 메시의 보다 복잡한 기능을 사용하는 데 중점을 둡니다. 고급 사용자는 필요한 경우 참조 가이드로 사용할 수 있는 간결한 튜토리얼을 찾을 수 있습니다. 엔드포인트 문서는 정확성 또는 일관성을 손상시키지 않고 쉽게 업데이트할 수 있는 방식으로 작성해야 합니다. 자동화된 프로세스여야 합니다.
리소스: 사용자 가이드: Google Developers Codelab - 포괄적인 최종 사용자용 대화식 가이드를 만드는 데 사용됩니다. 이점: - 샌드박스 튜토리얼을 만들 수 있습니다. - 직접 경험해 봅니다. - Google Docs를 사용하여 작성되며 마크다운 텍스트를 지원합니다. - Google Analytics를 이용하여 모니터링할 수 있습니다. - 사용자 트래픽을 쉽게 확인할 수 있습니다. - 사용이 간편합니다. 사용자가 직접적인 투자 없이 소프트웨어를 직접 사용해 볼 수 있도록 시각적으로 멋진 튜토리얼을 제작합니다.
Google Codelabs는 CLaaT (Codelabs) 프로젝트를 사용하여 개선하고 쉽게 배포할 수 있습니다. 이 프로그램은 마크다운을 사용하여 Google 문서로 작성된 튜토리얼을 Codelab (HTML) 형식으로 변환하는 데 사용되는 명령줄 도구를 제공하는 프로그램입니다.
사용자 가이드: Jekyll - 여기에 있는 Meshery.io의 기존 문서는 Jekyll에서 호스팅되며 Docsy Jekyll 테마를 사용합니다. 이 제품은 마크다운, liquid, HTML, CSS를 사용하여 호스팅 준비가 완료된 정적 웹사이트를 생성하고 Ruby 개발 환경에서 실행합니다. 이점: - GitHub 저장소에서 직접 사이트를 호스팅할 수 있습니다. - 매우 활발한 커뮤니티로 지원을 잘 받는 프로젝트입니다. - 다른 플랫폼으로 이전할 필요 없이 기존 SMI 및 Meshery 문서에 사용자 가이드 및 개선사항을 간단히 추가할 수 있습니다.
API 문서: Swagger (또는 Swaggo)는 SMI 및 Meshery용 API 문서를 만드는 데 사용됩니다. API 문서를 작성하기 위한 세련된 솔루션입니다. 이점: - API 설계 문서화: API가 발전함에 따라 문서가 최신 상태로 유지됩니다. - API 설계 문서: API 정의에서 자동 생성될 수 있습니다. - 여러 문서 버전 관리 - 맞춤 API 디자인
프로젝트 목표: - Google Developer Codelabs로 Meshery를 도구로 사용하여 SMI 및 관련 서비스 메시용 대화형 최종 사용자 튜토리얼을 만듭니다. - 서비스 메시에 Jekyll을 사용하여 최종 사용자 가이드 작성 - Swagger를 사용하여 SMI용 API 엔드포인트 문서를 생성합니다. - 미래와 현재 사용자 또는 개발자가 SMI 커뮤니티의 안내와 조정에 따라 쉽게 프로젝트에 계속 추가할 수 있도록 프로젝트 커뮤니티를 주도합니다.
타임라인: 제안된 타임라인은 다음 페이지에서 확인할 수 있습니다. https://docs.google.com/document/d/1If2mtBdWZer4qrh66NfXOWBx_3-tiA09jnoPMqy2lqs/edit#bookmark=kix.j1b6m64eubsl
구조: 제안된 사용자 가이드 구조는 다음 페이지에서 확인할 수 있습니다. https://docs.google.com/document/d/1A3YYAMUTe06MojNWo8hdF4KZbvr-qVaaA2myzWeshHQ/edit?usp=sharing
이 프로젝트가 필요한 이유 서비스 메시 커뮤니티는 최근 CNCF에 샌드박스 프로젝트로 통합되면서 매우 빠른 속도로 확장되고 있습니다. 하지만 이 프로젝트는 최종 사용자와 개발자 모두를 위해 문서화가 심각하게 부족함을 목격하고 있습니다. 이전에 EmojiVoto 앱이 있는 linkerD, Bookinfo 애플리케이션이 설치된 Istio, Hashicorp의 Consul을 비롯해 다양한 서비스 메시를 사용해 본 경험이 있습니다. 또한 SMI 트래픽 분할을 시도하고 서비스 메시 구성에 다양한 유효성 검사 규칙을 구현했습니다. 이 학습 과정은 매력적이긴 하지만 고도로 기술적인 과정이라 할 수 있으며 서비스 메시 커뮤니티에 대한 첫걸음을 내딛으려 하거나 자체 개인 또는 업무용 프로젝트에 서비스 메시를 활용하려는 신규 사용자는 물론 개발자에게도 부담이 될 수 있습니다. 저는 효율적이고 잘 문서화된 가이드와 튜토리얼을 통해서만 해결할 수 있는 이러한 격차를 해소하고자 합니다.