이 페이지에는 Google Season of Docs에 선정된 기술 문서 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 구성:
- Cloud Native Computing Foundation (CNCF)
- 기술 문서 작성자:
- Shriti
- 프로젝트 이름:
- SMI 및 관련 서비스 메시의 문서 개선
- 프로젝트 길이:
- 표준 기간 (3개월)
Project description
서비스 메시 기술은 기본적으로 모든 보안, 관리, 모니터링 요구사항을 처리하여 점점 늘어나는 서비스에 가치를 제공하는 것을 목표로 합니다. 서비스 메시 인터페이스 (SMI)는 가장 일반적인 서비스 메시 사용 사례 (트래픽 정책, 원격 분석, 전환)를 위한 API 집합을 정의하고 마이크로서비스 환경에서 서비스 간 통신을 처리하기 위한 전용 인프라 레이어인 서비스 메시 간의 호환성을 지원합니다. 이러한 인터페이스를 표준화하면 향상된 최종 사용자 환경을 제공할 수 있으므로 SMI 및 관련 서비스 메시의 향후 목표입니다.
현재 상태:
사용자 가이드: SMI는 2020년 4월에 CNCF에 기부된 비교적 새로운 샌드박스 프로젝트입니다. 따라서 프로젝트에 최종 사용자 문서가 부족합니다. Meshery는 다양한 서비스 메시의 성능 채택, 구성, 운영, 관리를 용이하게 하는 모든 종류의 서비스에 대한 성능 벤치마킹이 포함된 서비스 관리 영역으로, 모든 서비스 메시를 기반으로 실행되는 애플리케이션의 측정항목을 수집하고 표시합니다. 따라서 전체 SMI 사용자 커뮤니티의 출발점이 될 Meshery 가이드로 시작해 보고자 합니다.
사용자 튜토리얼: 기존 SMI 플랫폼 중 샘플 애플리케이션인 Learn Layer5는 현재 SMI 학습 기기 및 SMI 사양 유효성 검사를 실행하는 샘플 애플리케이션으로 사용됩니다.그 밖의 SMI 프로젝트에는 최종 사용자 튜토리얼이 전혀 없으며, 이는 프로젝트의 기술적 특성상 심각한 장애가 됩니다. Meshery는 SMI 및 관련 서비스 메시의 이점과 사용법을 보여주기에 완벽한 애플리케이션이므로 SMI의 기능을 보여주는 기본 도구로 사용하고자 합니다.
API 문서: 현재 존재하지 않습니다. SMI 및 다양한 관련 프로젝트에는 플랫폼에 정의된 API 엔드포인트가 있습니다. 예를 들어 Meshery에는 server.go (https://github.com/layer5io/meshery/blob/master/router/server.go)에 정의된 엔드포인트가 있지만 외부에서 잘 주석 처리되거나 문서화되지는 않았습니다. 이는 API의 의미 있는 문서로 해결할 수 있으며, 사용자가 엔드포인트를 테스트하고 기능을 미리 볼 수 있는 방법을 추가함으로써 이를 개선할 수 있습니다.
분석:
사용자 튜토리얼은 사용자가 소프트웨어를 사용하고 테스트 실행할 수 있도록 만들었습니다. 사용자의 관심을 사로잡으려면 대화형이면서 미적으로도 매력적이어야 하며 무엇보다 사용하기 쉬워야 합니다.
하지만 사용자 가이드는 참조 가이드 또는 문제를 빠르게 해결할 수 있는 장소로 사용되는 경우가 많으므로 사용자 가이드를 작성하거나 호스팅할 때는 더 성숙한 형식을 사용하는 것이 좋습니다. 상호작용이 아닌 잘 구성되어야 하며 명확성, 일관성, 우수한 사용자 흐름을 개선하는 데 중점을 두어야 합니다.
이 문제를 해결하려면 Google Codelab을 사용하여 별도의 사용자 튜토리얼을 만들고 Jekyll을 사용하여 독립적인 사용자 가이드를 만든 후 API 문서와 함께 통합하여 최종 사용자와 향후 공동작업자 모두에게 원활한 환경을 제공하는 것이 좋습니다.
대상 사용자: SME 프로젝트는 하위의 모든 프로젝트에 배포 및 운영 관행, 학습 환경, 성능 벤치마크를 제공합니다. 개인과 조직 모두를 대상으로 합니다.
사용자 가이드: 사용자에게 사전 IT 지식이 있다고 가정하지 않고 초보 사용자를 타겟팅합니다. 대상: 초보 사용자 이유: 주로 방대한 참조 가이드로 사용되며 시간이 지남에 따라 업데이트해야 합니다. 여기에는 사용자가 서비스 메시를 설정하고 사용하는 데 필요한 모든 정보를 갖추도록 하는 심층 설명과 유용한 도움말이 포함됩니다. 필요한 경우 동영상, 사진, 스크린샷, GIF를 추가하여 가이드를 더욱 매력적이고 사용자 친화적으로 만들 예정입니다.
사용자 튜토리얼: 대상: 초보 사용자 이유: 사용자의 관심을 끌고 소프트웨어를 원활하게 테스트 실행할 수 있도록 튜토리얼을 매력적이고 미적으로 호소력 있게 만드는 데 중점을 두고, 이를 통해 서비스 메시 인터페이스를 더 잘 이해할 수 있도록 할 것입니다.
API 엔드포인트 문서: 대상: 고급 사용자 이유: 이 섹션에서는 기본적인 수준의 IT 지식을 보유한 고급 사용자에게 더 유용한 서비스 메시의 더 복잡한 기능을 사용하는 방법을 중점적으로 설명합니다. 고급 사용자는 필요한 경우 참조 가이드로 사용할 수 있는 간결한 튜토리얼을 찾습니다. 엔드포인트 문서는 정확성이나 일관성을 손상시키지 않으면서 쉽게 업데이트할 수 있도록 작성해야 합니다. 자동화된 프로세스가 좋습니다.
리소스: 사용자 가이드: Google Developers Codelab - 포괄적인 최종 사용자 가이드를 만드는 데 사용됩니다. 이점: - 샌드박스 가이드를 만들 수 있습니다. - 실무적인 접근 방식을 사용합니다. - Google Docs를 사용하여 작성되었으며 마크다운 텍스트를 지원합니다. - Google 애널리틱스를 사용하여 모니터링할 수 있습니다. - 사용자 트래픽을 쉽게 관찰할 수 있습니다. - 사용하기 쉬움. 사용자가 직접 투자하지 않고도 소프트웨어와 직접 소통할 수 있는 심미적으로도 만족스러운 튜토리얼을 제작합니다.
Google Codelabs는 CLaaT (Codelabs as a Thing) 프로젝트를 사용하여 개선하고 쉽게 배포할 수 있습니다. 이 프로그램은 마크다운을 사용하여 Google 문서로 작성된 튜토리얼을 Codelab (HTML) 형식으로 변환하는 데 사용되는 명령줄 도구를 제공합니다.
사용자 가이드: Jekyll - 여기에서 확인할 수 있는 meshery.io의 기존 문서는 Jekyll에서 호스팅되며 Docsy Jekyll 테마를 사용합니다. Markdown, 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 트래픽 분할도 시도해 보고 서비스 메시 구성에 다양한 유효성 검사 규칙을 구현했습니다. 학습 프로세스는 매력적이지만 고도로 기술적으로 서비스 메시 커뮤니티에 첫걸음을 떼거나 개인적인 프로젝트 또는 전문 프로젝트에 서비스 메시를 활용하려는 신규 사용자뿐만 아니라 개발자에게도 흥미를 잃을 수 있습니다. 이 격차를 해소하고자 합니다. 이는 효율적이고 잘 문서화된 가이드와 튜토리얼로만 가능합니다.