Skip to content

Unify writing style and terminology across the docs - #51

Merged
Eundms merged 2 commits into
mainfrom
docs/style-consistency
Sep 23, 2026
Merged

Eundms merged 2 commits into
mainfrom
docs/style-consistency

Conversation

@Eundms

@Eundms Eundms commented Sep 23, 2026

Copy link
Copy Markdown
Contributor

Description

개요

  • 문서가 늘어나면서 문체·용어·표기가 문서마다 달라져, 같은 저장소의 글로 읽히지 않는 상태였습니다. 내용은 그대로 두고 표기와 구조만 맞췄습니다.
  • 규칙이 어디에도 적혀 있지 않아 같은 불일치가 반복되던 부분은 CONTRIBUTING.rst 와 리뷰 체크리스트에 명문화했습니다.
  • 번역 카탈로그가 1,608개 중 1개만 번역된 상태라, 원문 문장을 손대도 번역 손실이 사실상 없는 시점이라 판단했습니다.

표기 통일

  • 한다체로 쓰여 있던 4개 문서(kubernetes-csi, openstack-fundamentals, cni-and-neutron, neutron-helm-chart)를 합니다체로 맞췄습니다. glossary.rst 는 사전체라 그대로 두었습니다.
  • 로마자 뒤 조사를 띄어쓰기로 통일했습니다(약 300곳). 코드 블록과 ASCII 도식, 숫자 뒤 조사(폭이 2로), 슬래시 복합어(CPU/메모리)는 제외했습니다.
  • 파드→Pod, 가상 머신→VM, 옥타비아→Octavia, OpenStack-Helm/OSH→openstack-helm, K8s→Kubernetes 로 용어집 표제어에 맞췄습니다.
  • 용어 첫 등장 표기가 세 가지로 섞여 있어 한글(English, ABBR) 형식으로 통일했습니다.

구조

  • ovn-ovs, openstack-helm-network-outline 이 최상위 절에 - 를 쓰고 있어 CONTRIBUTING.rst 규정대로 = 로 고쳤고, 제목 밑줄 길이를 제목 폭에 맞췄습니다.
  • 용어집에 본문에서 쓰면서 빠져 있던 12개 항목(libvirt, KVM, QEMU, cgroup, VXLAN, ML2, Placement, Horizon, Calico, Kubespray, kOps, amphora)을 추가하고, 첫 등장에 :term: 을 걸었습니다. (15회/3개 문서 → 41회/11개 문서)
  • 분량이 큰 본문 문서들이 toctree 말고는 도달 경로가 없어서, 관련 문서에서 :doc: 로 연결했습니다. (인바운드 링크 0인 문서 15개 → 0개)

수정

  • 리다이렉트되는 외부 링크 8개를 최종 URL로 교체했습니다. (docs.openstack.org/magnum/ → .../magnum/latest/ 등)
  • 문장 전체를 인라인 리터럴로 감싼 2곳을 굵은 글씨로, :code: 역할 1곳을 인라인 리터럴로, 수동 번호 목록을 #. 로 바꿨습니다.

도구

  • tox -e linkcheck 환경을 추가하고 CI에 continue-on-error 단계로 넣었습니다. 깨진 링크와 리다이렉트를 알리되 빌드는 막지 않습니다.
  • 비어 있던 intersphinx_mapping = {} 과 해당 확장을 제거했습니다. 다시 켜는 방법은 주석으로 남겼습니다.

Type of change

  • 📝 Documentation content (new or edited pages)
  • 🌐 Translation / i18n (localization)
  • 🐛 Fix (typo, broken link, build error, wrong information)
  • 🔧 Tooling / CI / repository structure
  • Other:

Related issue

Fixes #50

Checklist

  • I read the Contributing Guide.
  • The documentation builds locally: tox -e docs
  • The rST sources pass lint: tox -e pep8
  • New pages are registered in the parent index.rst toctree. (새 문서 없음)
  • rST conventions are followed (one sentence per line, line length < 79,
    heading levels, 한글(English) on first use of a term).

Additional notes

리뷰 시 봐주셨으면 하는 부분

  • foundations/kubernetes-csi.rst 의 "세부 구조" 절은 표기 수정이 아니라 내용을 고쳤습니다. kubelet 이 CSI 컴포넌트로 적혀 있고 "~를 통해 ~를 통해" 로 문장이 깨져 있어, 컨트롤러 플러그인 / 노드 플러그인 두 종류와 이를 UNIX 소켓으로 호출하는 kubelet 구조로 다시 썼습니다. 원저자 의도와 맞는지 확인이 필요합니다.
  • 제목 밑줄 길이를 제목 폭에 맞추면서, 내용 변경이 없는 문서도 diff에 포함됐습니다. 밑줄만 바뀐 문서가 여럿 있습니다.
  • linkcheck 에서 netapp.com 링크는 봇 접근에만 403 을 돌려주고 사람은 정상적으로 볼 수 있어, 링크를 지우는 대신 linkcheck_ignore 에 사유와 함께 등록했습니다.

검증

검사 결과
tox -e docs (한국어, -W) 통과
tox -e docs-en (영어 /en/, -W) 통과
tox -e pep8 (doc8, 61개 파일) 오류 0
tox -e linkcheck 깨짐 0, 리다이렉트 0 (이전 깨짐 1, 리다이렉트 8)

The pages had drifted into two Korean writing styles and several
spellings for the same thing, so they read like they came from
different projects.

Move the four remaining 한다체 documents to 합니다체 and leave the
glossary in its dictionary style. Put a space between a Latin word and
the Korean particle that follows it, the way most of the docs already
did. Settle on the glossary headwords for Pod, VM, Octavia,
openstack-helm and Kubernetes.

ovn-ovs and openstack-helm-network-outline used '-' for their top-level
sections, which contradicts CONTRIBUTING, so promote them to '=' and
size every title decoration to the width of its title.

Point the eight redirecting links at their final URLs, turn two
sentences wrapped in inline literals into bold text, replace the one
:code: role with an inline literal, and let the numbered list number
itself.

Add the terms the newer pages already use - libvirt, KVM, QEMU, cgroup,
VXLAN, ML2, Placement, Horizon, Calico, Kubespray, kOps, amphora - to
the glossary and link first mentions with :term:. The longest pages
were reachable only through a toctree, so link them from the documents
that lead into them.

Rewrite the CSI component section, which listed kubelet as a CSI
component and lost a sentence along the way. It is the controller and
node plugins, with kubelet calling the node plugin over a UNIX socket.
Nothing checked the conventions the docs were meant to follow, so the
same inconsistencies kept coming back.

Add a linkcheck tox environment and run it in CI without failing the
build, so broken links and redirects surface on their own.

Write the Korean prose rules - sentence style, particle spacing, term
notation on first use, preferred spellings - along with the markup and
link rules into CONTRIBUTING, and add the matching items to the
contributor and reviewer checklists.

Drop sphinx.ext.intersphinx and its empty mapping; a comment says how
to turn it back on when there is something to point at.
@Eundms
Eundms merged commit 6058182 into main Sep 23, 2026
2 checks passed
@Eundms
Eundms deleted the docs/style-consistency branch September 23, 2026 00:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Writing style and terminology are inconsistent across the docs

1 participant