스타일 가이드

이 스타일 가이드는 용어집의 독자, 용어 정의 형태, 요구되는 설명의 수준 및 일관된 스타일을 유지하는 방법을 이해하는 데 도움을 줄 것이다.

클라우드 네이티브 용어집은 CNCF 저장소의 기본 스타일 가이드를 따른다. 추가적으로, 다음 규칙도 적용된다.

  1. 간단하고 이해하기 쉬운 언어를 사용하고, 전문 용어와 유행어는 피한다.
  2. 구어체는 사용하지 않는다.
  3. 정확하고 구체적인 언어를 사용한다.
  4. 축약형은 사용하지 않는다.
  5. 수동태 사용을 줄인다.
  6. 긍정 형태의 문장을 사용하도록 노력한다.
  7. 인용문 외에는 느낌표를 사용하지 않는다.
  8. 과장하지 않는다.
  9. 반복 표현을 피한다.
  10. 간결한 표현을 사용한다.

용어집의 대상 독자

용어집은 기술에 익숙한 사람과 익숙하지 않은 사람 모두를 위해 작성되었다. 각 정의는 간단한 용어로 작성되어야 하고, 모두가 기술적 지식을 갖고 있다고 생각해서는 안 된다. 아래의 “정의” 섹션에서 더 자세히 설명한다.

용어 정의 템플릿

각 용어집 용어는 마크다운 파일로 저장되어 있으며 다음의 템플릿을 따른다.

---
title: 
status: 
category: 
---

## What it is (개념)

기술 또는 개념에 대한 간략한 요약

## Problem it addresses (다루는 문제)

이 기술 또는 개념이 다루는 문제에 대한 설명

## How it helps (문제 해결 방식)

이 기술 또는 개념이 문제를 어떻게 해결하는지에 대한 설명

Title (제목)

title 레이블은 정의 레이아웃에서 항상 맨 위에 있으며, 이 레이블의 값에는 대소문자를 알맞게 사용해야 한다.

---
title: Definition Template

Status (상태)

status 레이블은 title 레이블 밑에 위치한다. status 레이블은 해당 용어 정의가 철저히 검증되었는지 또는 더 많은 노력이 필요한지 여부를 나타낸다.

status 레이블에 대한 유효한 값은 다음과 같다.

  • Completed
  • Feedback Appreciated
  • Not Started

완료된 용어 정의에 대해 항상 이슈를 열 수 있다. 용어 정의가 유동적인 동안에는 해당 용어 정의의 상태가 Feedback Appreciated로 변경될 것이다.

---
title: Definition Template
status: Feedback Appreciated

Category (카테고리)

category 레이블은 status 레이블 밑에 위치한다. 이 레이블의 값은 다음 중 하나여야 한다.

  • Technology (기술)
  • Property (속성)
  • Concept (개념)
---
title: Definition Template
status: Feedback Appreciated
category: Concept
---

용어 정의

세 개의 소제목

technology (기술) 및 concept (개념) 카테고리에 속하는 용어 정의는 다음 세 개의 소제목을 포함한다.

  • What it is (개념): 지금 다루는 것에 대한 짧고 명확한 개요을 제공한다.
  • Problem it addresses (다루는 문제): 문제 해결 방식이 아닌 문제 자체에 대해 설명한다(문제 해결 방식은 다음 섹션에서 제시하므로). 문제를 설명하기 위해 소개하려는 대상을 언급하지 않는다. 우리가 무엇 때문에 그것이 필요한지에 집중하여 작성한다.
  • How it helps (문제 해결 방식): 이제 다시 소개하려는 대상으로 돌아온다. 위에서 설명한 문제를 어떻게 해결하는가?

properties (속성) 카테고리에 속하는 용어 정의는 여러 섹션이 필요하지 않다. 용어 정의 만으로도 충분하다.

가장 중요한 것은 품질

당신의 제안이 머지되면, 당신의 제안이 곧 그 용어에 대한 공식적인 CNCF 정의가 된다(다른 누군가가 개선하기 전 까지는). CNCF의 높은 수준을 만족하는 용어 정의를 만드는 것에 서둘러서는 안 된다. 높은 품질에는 시간과 노력이 필요하다.

조사하라: 용어를 알고 있다고 확신하더라도, 올바르게 이해했는지 다시 확인한다. 우리는 용어를 사용할 때 종종 큰 그림을 반영하지 못하는 방식으로 용어를 사용할 때도 있다. 용어에 대해 조사할 때, 특히 용어에 대해 100% 자신있는 경우가 아니라면, 다양한 소스를 참고한다. 많은 용어 정의가 편향적으로 작성되어 있을 수 있으며, 특히 각 업체에서 작성한 경우 더욱 그러할 수 있다. 용어집은 업체 중립적이고 전 세계적으로 받아들여지는 정의를 포함해야 한다.

표절하지 않는다. 다른 공식적인 출판물과 마찬가지로 용어집에도 동일한 규칙이 적용된다. 다른 사람의 작업을 인용하고 이에 대해 기여하는 경우를 제외하고는, 다른 사람의 작업을 복사하여 붙여넣기해서는 안 된다. 다른 사람이 작성한 정의의 특정 부분이 마음에 든다면, 당신의 언어로 바꾸어 표현한다.

간결하게 유지

용어집의 목표는 복잡한 개념을 쉬운 단어로 설명하는 것이다. 이는 여러 번의 수정이 필요할 수도 있는 매우 어려운 작업이다. 용어 정의 초안을 작성할 때, 항상 용어집을 보게 될 대상을 염두에 둔다. 업계 용어와 유행어는 사용하지 않는다. 작성 중에 무의식적으로 사용했다면 해당 부분으로 돌아가 수정한다.

적절한 경우, 당신이 설명하는 개념이 언제 그리고 왜 관련성이 있는지 독자(특히 비기술적인 사람)가 더 잘 이해할 수 있도록 하는 실제 사례 를 사용한다.

이미 존재하는 용어집 용어를 문서에 사용한 경우, 해당 용어집 용어로 링크를 건다 (맨 처음 언급에만 링크를 걸어야 한다).

예시: 서비스 메시(service mesh) 정의의 “개념” 섹션을 참고한다. 마이크로서비스, 서비스, 안정성, 관찰 가능성(observability) 항목으로 가는 링크가 존재한다. 또한, 마이크로서비스 환경의 네트워크 문제(기술적이지 않은 사람은 이해할 수 없음)와 Wi-Fi 문제(노트북을 사용하는 사람이면 누구나 이해할 수 있음)를 비교하는 실제 사례를 사용한다. 가능한 경우, 이러한 연관 관계를 소개한다.

Google 또는 Word 문서로 시작

Google 또는 Word 문서로 시작하여, 며칠을 두고 계속 개선하는 것을 추천한다. 이렇게 하면 구문이나 표현을 더 간단하고 이해하기 쉽게 개선할 수도 있다. 또한 PR을 제출하기 전에 맞춤법 검사를 실행해야 한다.

당신이 해당 용어에 작업하는 동안 다른 사람이 동일한 용어에 대한 PR을 여는 일이 없도록 하기 위해, 이슈에 작업 의사를 밝히거나 새로운 이슈를 생성하고, 할당을 받는다. 더 자세한 사항은 기여 방법 문서를 참고한다.

시작하기 전에, 게시되어 있는 용어집 용어 몇 개를 읽어 보고 설명 수준, 난이도, 예시를 소개하면 좋은 상황 등을 파악한다.

리뷰 프로세스 - 어떤 일이 일어나는가

현재 몇 명의 메인테이너가 여유 시간에 리뷰를 수행하고 있음을 참고한다. 용어 제안을 빠르게 리뷰할 때도 있지만, 시간이 걸릴 때도 있다. 인내심을 가져야 한다. 질문이 있다면, #glossary 슬랙 채널에 문의한다(기여 방법 문서 참고).

우리의 목표는 용어집을 최고의 자원으로 만드는 것이다. 당신이 PR을 제출하면, 리뷰어 또는 메인테이너가 하나 이상의 수정을 요청할 수 있다. 많은 PR이 이러한 상황을 겪으므로, 좌절할 필요는 없다. 이러한 리뷰&수정 과정과 협력을 통해, 당신의 기여로부터 전 세계의 독자가 읽고 참조하는 유용한 정의가 탄생한다.

최근 수정 August 16, 2022: Some fixes (#1181) (e8cb8ee)