마크다운 문서 작성 컨벤션 통일하기

[J3m3]

이 이슈는 마크다운 문서 작성 컨벤션을 어떻게 통일할 것인지 토의하려는 목적으로 만들어졌습니다.

현재 문서 전반에 걸쳐 백틱(``), 볼드(** **), 따옴표(" " 혹은 ' '), 수평선(---) 등과 같은 마크다운 서식들이 일관된 기준 없이 다양한 상황에 혼용되고 있습니다.

이로 인해 문서의 일관성이 떨어지면, 문서를 읽는 독자는 물론 새로운 기여자에게 혼선을 줄 수 있습니다. 나아가, 서식만으로 의미가 명확히 드러난다는 통일된 컨벤션의 이점 역시 살릴 수 없게 됩니다.

따라서 문서 작성 컨벤션을 간단하게나마 정의하고, 모두가 참고할 수 있도록 contributing.md에 추가하는 것이 좋아 보입니다.

Cc: @Jjungs7 @jimmy0006

[Jjungs7]

제가 주로 사용하는 포맷팅 형식은 다음과 같습니다

• 백틱: 실행 가능한 one liner 코드
• 따옴표: 이름, 변수. 쌍 따옴표(")만 사용
• 볼드: 강조하고자 하는 키워드나 개념. 최소한으로만 사용. 문단에서 강조하고자 하는 키워드 위주로만 사용
• 수평선: 사용하지 않음
• blocks ([!NOTE], [!TIP], 등): 한 절에서 권장 0 ~ 1개, 최대 2개

[J3m3]

파일명 및 파일 내용물

• 백틱: 실행 가능한 one liner 코드
• 따옴표: 이름, 변수. 쌍 따옴표(")만 사용
• 볼드: 강조하고자 하는 키워드나 개념. 최소한으로만 사용. 문단에서 강조하고자 하는 키워드 위주로만 사용
• 수평선: 사용하지 않음
• blocks ([!NOTE], [!TIP], 등): 한 절에서 권장 0 ~ 1개, 최대 2개

아래 두 항목에 대해서는 어떻게 생각하시나요? 일단 위 기준상 가장 적합한 서식은 큰따옴표인 것 같아요.

• "/etc/kubernetes"와 같은 파일/디렉토리 이름
• ".spec.template.spec.containers[0].image"와 같은 필드값

K8s API Object

쿠버네티스 공식 문서에서는 Namespace, ConfigMap과 같은 API Object에 대해 Pascal case를 사용하는데, 저희도 이에 맞춰서 통일하는 게 좋을 것 같아요.

코드 블록

코드 블록에 관한 내용도 명문화되면 좋을 것 같아요.

1. 명령어의 output을 보여주지 않아도 될 경우, 쉘 프롬프트 없이 "sh" 코드블록 사용
   • 현재 "bash" 코드 블록을 사용 중이긴 한데, here-doc이나 multi-line command, ! 등이 모두 POSIX standard를 만족해서 "sh"로 통일하는 게 더 나을 것 같아요.

```sh
kubectl apply -f foo.yaml bar.yaml
```

2. 명령어의 output을 보여주어야 하는 경우, 쉘 프롬프트와 함께 "console" 코드블록 사용
   • 이때 $ 프롬프트는 non-root 유저로 명령어를 실행해야 할 때, # 프롬프트는 root 유저로 명령어를 실행해야 할 때로 구분하면 좋을 것 같아요.

```console
$ kubectl get ns
NAME                 STATUS   AGE
argocd               Active   89d
cilium-secrets       Active   106d
...
```

수정:
찾아보니 "sh"와 "bash"가 alias로 처리되는 것 같긴 하네요... 어느 쪽이든 크게 상관은 없을 것 같지만, "sh"가 더 짧으니 저는 이쪽으로 통일하는 게 더 나을 것 같아요.

[J3m3]

서식과는 조금 별개의 내용이긴 한데, 아래 사항도 하나로 통일하는 것이 좋아 보입니다.

• "PoolC" vs "풀씨"
• "Nginx" -> "NGINX"

[Jjungs7]

아래 두 항목에 대해서는 어떻게 생각하시나요? 일단 위 기준상 가장 적합한 서식은 큰따옴표인 것 같아요.

• "/etc/kubernetes"와 같은 파일/디렉토리 이름
• ".spec.template.spec.containers[0].image"와 같은 필드값

저는 따옴표가 좋은 것 같아요. 다른 의견도 주세요

K8s API Object

쿠버네티스 공식 문서에서는 Namespace, ConfigMap과 같은 API Object에 대해 Pascal case를 사용하는데, 저희도 이에 맞춰서 통일하는 게 좋을 것 같아요.

👍

1. 명령어의 output을 보여주지 않아도 될 경우, 쉘 프롬프트 없이 "sh" 코드블록 사용

   • 현재 "bash" 코드 블록을 사용 중이긴 한데, here-doc이나 multi-line command, ! 등이 모두 POSIX standard를 만족해서 "sh"로 통일하는 게 더 나을 것 같아요.

저도 sh 가 좋습니다

명령어의 output을 보여주어야 하는 경우, 쉘 프롬프트와 함께 "console" 코드블록 사용

• 이때 $ 프롬프트는 non-root 유저로 명령어를 실행해야 할 때, # 프롬프트는 root 유저로 명령어를 실행해야 할 때로 구분하면 좋을 것 같아요.

구분감을 위해서 한 줄 띄어쓰는것으로 의견드려요

$ kubectl get ns

NAME                 STATUS   AGE
argocd               Active   89d
cilium-secrets       Active   106d
...

$, # 구분은 이견 없는데, 포맷팅 가이드를 한 곳에 모아두면 읽는 사람도 편해질거같네요
아아아주 처음 $, # 를 봤을때 왜 명령어 앞에 주석 문자를 달아놨지? 라는 생각을 했던 기억이 있네요 허허

[Jjungs7]

서식과는 조금 별개의 내용이긴 한데, 아래 사항도 하나로 통일하는 것이 좋아 보입니다.

• "PoolC" vs "풀씨"
• "Nginx" -> "NGINX"

전 가능하면 영문자를 쓰는 편이라 PoolC 가 좋긴해요. 근데 이정도는 혼용해도 되지 않나 싶기도 하네요

제품은 공식 명칭을 따라가되, 엄격할 필요는 없다는 의견입니다

• ✅ ingress-nginx
• ✅ ingress-NGINX
• ✅ ingress nginx
• ✅ ingress NGINX
• ❌ ing NGINX (불필요한 줄여쓰기 금지)
• ❌ nginx (아예 다른 제품임)
• ❌ nginx ingress (아예 다른 제품임)
• ❌ ingress (문맥상 ingress nginx controller 인데 ingress 라 말하는 경우. Ingress object 인지 Ingress-NGINX 인지 알기 어려움)

[jimmy0006]

명령어의 output을 보여주어야 하는 경우, 쉘 프롬프트와 함께 "console" 코드블록 사용

• 이때 $ 프롬프트는 non-root 유저로 명령어를 실행해야 할 때, # 프롬프트는 root 유저로 명령어를 실행해야 할 때로 구분하면 좋을 것 같아요.

구분감을 위해서 한 줄 띄어쓰는것으로 의견드려요

$ kubectl get ns

NAME                 STATUS   AGE
argocd               Active   89d
cilium-secrets       Active   106d
...

$, # 구분은 이견 없는데, 포맷팅 가이드를 한 곳에 모아두면 읽는 사람도 편해질거같네요
아아아주 처음 $, # 를 봤을때 왜 명령어 앞에 주석 문자를 달아놨지? 라는 생각을 했던 기억이 있네요 허허

한 줄 띄우는 것에 동의합니다.
현재 문서에는 긴 명령어가 없지만, 만약 줄이 넘어가는 긴 명령어가 있을 경우 구분감을 위해 띄워야 할 것을 생각하면, 처음부터 한 줄 띄우는 것으로 가는게 좋겠네요.

• 백틱: 실행 가능한 one liner 코드
• 따옴표: 이름, 변수. 쌍 따옴표(")만 사용
• 볼드: 강조하고자 하는 키워드나 개념. 최소한으로만 사용. 문단에서 강조하고자 하는 키워드 위주로만 사용
• 수평선: 사용하지 않음
• blocks ([!NOTE], [!TIP], 등): 한 절에서 권장 0 ~ 1개, 최대 2개

실행 가능한 one liner 코드 외에도,
코드의 일부분을 가리킬 때 백틱을 사용하는 것은 어떨까요?

예시 1. 코드 내의 변수를 기리킬 때

$NAMESPACE_NAME 부분을 이전에 설정한 값으로 변경해주세요!

kubectl delete namespace $NAMESPACE_NAME

예시 2. 코드 내의 일부분을 가져와 설명할때

# 리소스 요청량 및 최대 제한량을 설정합니다. (성능 및 안정성 확보)
resources:
  requests:
    cpu: "50m"
    memory: "64Mi"
  limits:
    cpu: "100m"
    memory: "128Mi"

requests (요청량): 최소 리소스 보장량입니다. 쿠버네티스는 이 요청량을 보고 앱을 어디에 배치할지 결정합니다.

• cpu: "50m": CPU 성능을 0.05코어는 보장받습니다.
• memory: "64Mi": 메모리를 최소 64MiB는 확보합니다.

[J3m3]

2025/09/25 회의 내용

합의된 서식 컨벤션

1. 백틱을 활용한 인라인 코드: 쿠버네티스의 공식 문서 방식 차용
   • 코드, 명령어, 파일명, 필드명(ex. .spec.template.spec.containers[0].name) 등에 활용
   • https://kubernetes.io/docs/contribute/style/style-guide/#use-code-style-for-filenames-directories-and-paths
   • https://kubernetes.io/docs/contribute/style/style-guide/#inline-code-formatting
2. 볼드: 문단 내에서 강조가 필요한 키워드, 개념에 최소한으로 사용
3. 수평선: 사용하지 않음
4. 인용, Alert 블록: 한 절에서 권장 0 ~ 1개, 최대 2개
5. "큰따옴표": 나머지 서식 규칙을 해치지 않는 선에서 사용
6. sh 코드 블록: 명령어의 output을 보여주지 않아도 되는 경우에 사용
7. console 코드 블록: 명령어의 output을 보여주어야 하는 경우에 사용
   • output과 명령어는 하나의 추가적인 newline으로 구분
   • $ 프롬프트는 non-root 유저로 명령어를 실행해야 하는 경우에 사용
   • # 프롬프트는 root 유저로 명령어를 실행해야 하는 경우에 사용
   • # 프롬프트는 터미널 환경이 익숙지 않은 독자 입장에서 헷갈리 수 있으므로, 문서화 필요
     (문서에 root 권한이 필요한 명령어가 흔하지 않을 것이라는 점을 고려해, 필요한 경우 lazy하게 문서화)
8. K8s API Ojbect: 쿠버네티스 공식 문서 방식 차용
   • PascalCase 사용

합의된 기타 사항

1. "PoolC vs 풀씨", "NGINX vs Nginx vs ...": 오해의 소지가 없는 한 혼용 허용